Merge branch '5.next' into 5.x

Author: markstory

config/conf.py

@@ -10,13 +10,13 @@
 # built documents.
 #
 # The short X.Y version.
-version = '5.x'
+version = '5.next'
 
 # The full version, including alpha/beta/rc tags.
-release = '5.x'
+release = '5.next'
 
 # The search index version.
-search_version = '5'
+search_version = '5-next'
 
 # The marketing diplay name for the book.
 version_name = 'Chiffon'
@@ -32,14 +32,14 @@
     {'name': '1.1', 'number': '1.1', 'title': '1.1 Book'},
 ]
 # Enables the 'development version banner'
-is_prerelease = False
+is_prerelease = True
 
 # Languages available.
 languages = ['en', 'pt_BR', 'es', 'ja', 'fr']
 
 # The GitHub branch name for this version of the docs
 # for edit links to point at.
-branch = '5.x'
+branch = '5.next'
 
 # Add any paths that contain custom themes here, relative to this directory.
 html_theme_path = []

en/appendices/5-2-migration-guide.rst

@@ -0,0 +1,137 @@
+5.2 Migration Guide
+###################
+
+The 5.2.0 release is a backwards compatible with 5.0. It adds new functionality
+and introduces new deprecations. Any functionality deprecated in 5.x will be
+removed in 6.0.0.
+
+Behavior Changes
+================
+
+- ``ValidationSet::add()`` will now raise errors when a rule is added with
+  a name that is already defined. This change aims to prevent rules from being
+  overwritten by accident.
+- ``Http\Session`` will now raise an exception when an invalid session preset is
+  used.
+- ``FormProtectionComponent`` now raises ``Cake\Controller\Exception\FormProtectionException``. This
+  class is a subclass of ``BadRequestException``, and offers the benefit of
+  being filterable from logging.
+- ``NumericPaginator::paginate()`` now uses the ``finder`` option even when a ``SelectQuery`` instance is passed to it.
+
+Deprecations
+============
+
+Console
+-------
+
+- ``Arguments::getMultipleOption()`` is deprecated. Use ``getArrayOption()``
+  instead.
+
+Datasource
+----------
+
+- The ability to cast an ``EntityInterface`` instance to string has been deprecated.
+  You should ``json_encode()`` the entity instead.
+
+- Mass assigning multiple entity fields using ``EntityInterface::set()`` is deprecated.
+  Use ``EntityInterface::patch()`` instead. For e.g. change usage like
+  ``$entity->set(['field1' => 'value1', 'field2' => 'value2'])`` to
+  ``$entity->patch(['field1' => 'value1', 'field2' => 'value2'])``.
+
+Event
+-----
+
+- Returning values from event listeners / callbacks is deprecated. Use ``$event->setResult()``
+  instead or ``$event->stopPropogation()`` to just stop the event propogation.
+
+View
+----
+
+- The ``errorClass`` option of ``FormHelper`` has been deprecated in favour of
+  using a template string. To upgrade move your ``errorClass`` definition to
+  a template set. See :ref:`customizing-templates`.
+
+
+New Features
+============
+
+Console
+-------
+
+- The ``cake counter_cache`` command was added. This command can be used to
+  regenerate counters for models that use ``CounterCacheBehavior``.
+- ``ConsoleIntegrationTestTrait::debugOutput()`` makes it easier to debug
+  integration tests for console commands.
+- ``ConsoleInputArgument`` now supports a ``separator`` option. This option
+  allows positional arguments to be delimited with a character sequence like
+  ``,``. CakePHP will split the positional argument into an array when arguments
+  are parsed.
+- ``Arguments::getArrayArgumentAt()``, and ``Arguments::getArrayArgument()``
+  were added. These methods allow you to read ``separator`` delimitered
+  positional arguments as arrays.
+- ``ConsoleInputOption`` now supports a ``separator`` option. This option
+  allows option values to be delimited with a character sequence like
+  ``,``. CakePHP will split the option value into an array when arguments
+  are parsed.
+- ``Arguments::getArrayArgumentAt()``, ``Arguments::getArrayArgument()``, and
+  ``Arguments::getArrayOption()``
+  were added. These methods allow you to read ``separator`` delimitered
+  positional arguments as arrays.
+
+Database
+--------
+
+- The ``nativeuuid`` type was added. This type enables ``uuid`` columns to be
+  used in Mysql connections with MariaDB. In all other drivers, ``nativeuuid``
+  is an alias for ``uuid``.
+- ``Cake\Database\Type\JsonType::setDecodingOptions()`` was added. This method
+  lets you define the value for the ``$flags`` argument of ``json_decode()``.
+- ``CounterCacheBehavior::updateCounterCache()`` was added. This method allows
+  you to update the counter cache values for all records of the configured
+  associations. ``CounterCacheCommand`` was also added to do the same through the
+  console.
+- ``Cake\Database\Driver::quote()`` was added. This method provides a way to
+  quote values to be used in SQL queries where prepared statements cannot be
+  used.
+
+Datasource
+----------
+
+- Application rules can now use ``Closure`` to define the validation message.
+  This allows you to create dynamic validation messages based on the entity
+  state and validation rule options.
+
+Error
+-----
+
+- Custom exceptions can have specific error handling logic defined in
+  ``ErrorController``.
+
+ORM
+---
+
+- ``CounterCacheBehavior::updateCounterCache()`` has been added. This method
+  allows you to update the counter cache values for all records of the configured
+  associations.
+- ``BelongsToMany::setJunctionProperty()`` and ``getJunctionProperty()`` were
+  added. These methods allow you to customize the ``_joinData`` property that is
+  used to hydrate junction table records.
+- ``Table::findOrCreate()`` now accepts an array as second argument to directly pass data in.
+
+TestSuite
+---------
+
+- ``TestFixture::$strictFields`` was added. Enabling this property will make
+  fixtures raise an error if a fixture's record list contains fields that do not
+  exist in the schema.
+
+View
+----
+
+- ``FormHelper::deleteLink()`` has been added as convenience wrapper for delete links in
+   templates using ``DELETE`` method.
+- ``HtmlHelper::importmap()`` was added. This method allows you to define
+  import maps for your JavaScript files.
+- ``FormHelper`` now uses the ``containerClass`` template to apply a class to
+  the form control div. The default value is ``input``.
+

en/appendices/migration-guides.rst

@@ -10,4 +10,5 @@ each version and the migration path between 5.x minor releases.
     ./5-0-upgrade-guide
     ./5-0-migration-guide
     ./5-1-migration-guide
+    ./5-2-migration-guide
     ./phpunit10

en/console-commands.rst

@@ -145,6 +145,7 @@ CakePHP Provided Commands
 
     console-commands/cache
     console-commands/completion
+    console-commands/counter-cache
     console-commands/i18n
     console-commands/plugin
     console-commands/schema-cache

en/console-commands/commands.rst

@@ -298,10 +298,6 @@ To get started testing your console application, create a test case that uses th
 ``exec()`` that is used to execute your command. You can pass the same string
 you would use in the CLI to this method.
 
-.. note::
-
-    For CakePHP 4.4 onwards the ``Cake\Console\TestSuite\ConsoleIntegrationTestTrait`` namespace should be used.
-
 Let's start with a very simple command, located in
 **src/Command/UpdateTableCommand.php**::
 
@@ -549,6 +545,20 @@ assertion methods that make help assert against console output::
     // assert that stderr matches a regular expression
     $this->assertErrorRegExp($expected);
 
+Debug Helpers
+-------------
+
+You can use ``debugOutput()`` to output the exit code, stdout and stderr of the
+last run command::
+
+    $this->exec('update_table Users');
+    $this->assertExitCode(Command::CODE_SUCCESS);
+    $this->debugOutput();
+
+.. versionadded:: 4.2.0
+   The ``debugOutput()`` method was added.
+
+
 Lifecycle Callbacks
 ===================
 

en/console-commands/counter-cache.rst

@@ -0,0 +1,24 @@
+CounterCache Tool
+#################
+
+The CounterCacheCommand provides a CLI tool for rebuilding the counter caches
+in your application and plugin models. It can be used in maintenance and
+recovery operations, or to populate new counter caches added to your
+application.
+
+.. code-block:: console
+
+   bin/cake counter_cache --assoc Comments Articles
+
+This would rebuild the ``Comments`` related counters on the ``Articles`` table.
+For very large tables you may need to rebuild counters in batches. You can use
+the ``--limit`` and ``--page`` options to incrementally rebuild counter state.
+
+.. code-block:: console
+
+   bin/cake counter_cache --assoc Comments --limit 100 --page 2 Articles
+
+When ``limit`` and ``page`` are used, records will be ordered by the table's
+primary key.
+
+.. versionadded:: 5.2.0

en/console-commands/option-parsers.rst

@@ -59,11 +59,16 @@ You can use the following options when creating an argument:
 * ``choices`` An array of valid choices for this argument. If left empty all
   values are valid. An exception will be raised when parse() encounters an
   invalid value.
+* ``separator`` A character sequence that separates arguments that should be
+  parsed into an array.
 
 Arguments that have been marked as required will throw an exception when
 parsing the command if they have been omitted. So you don't have to
 handle that in your shell.
 
+.. versionadded:: 5.2.0
+    The ``separator`` option was added.
+
 Adding Multiple Arguments
 -------------------------
 
@@ -140,10 +145,16 @@ of the option:
   Defaults to ``false``.
 * ``multiple`` - The option can be provided multiple times. The parsed option
   will be an array of values when this option is enabled.
+* ``separator`` - A character sequence that the option value is split into an
+  array with.
 * ``choices`` - An array of valid choices for this option. If left empty all
   values are valid. An exception will be raised when parse() encounters an
   invalid value.
 
+
+.. versionadded:: 5.2.0
+    The ``separator`` option was added.
+
 Adding Multiple Options
 -----------------------
 

en/console-commands/schema-cache.rst

@@ -1,7 +1,7 @@
 Schema Cache Tool
 #################
 
-The SchemaCacheShell provides a simple CLI tool for managing your application's
+The SchemaCacheCommand provides a simple CLI tool for managing your application's
 metadata caches. In deployment situations it is helpful to rebuild the metadata
 cache in-place without clearing the existing cache data. You can do this by
 running:

en/controllers/components/form-protection.rst

@@ -146,13 +146,16 @@ configuration option to a callback function in the controller.
 By configuring a callback method you can customize how the failure handling process
 works::
 
+    use Cake\Controller\Exception\FormProtectionException;
+
     public function beforeFilter(EventInterface $event)
     {
         parent::beforeFilter($event);
 
         $this->FormProtection->setConfig(
             'validationFailureCallback',
-            function (BadRequestException $exception) {
+            // Prior to 5.2 use Cake\Http\Exception\BadRequestException.
+            function (FormProtectionException $exception) {
                 // You can either return a response instance or throw the exception
                 // received as argument.
             }

en/development/errors.rst

@@ -210,6 +210,30 @@ prefix. You could create the following class::
 This controller would only be used when an error is encountered in a prefixed
 controller, and allows you to define prefix specific logic/templates as needed.
 
+Exception specific logic
+------------------------
+
+Within your controller you can define public methods to handle custom
+application errors. For example a ``MissingWidgetException`` would be handled by
+a ``missingWidget()`` controller method, and CakePHP would use
+``templates/Error/missing_widget.php`` as the template. For example::
+
+    namespace App\Controller\Admin;
+
+    use App\Controller\AppController;
+    use Cake\Event\EventInterface;
+
+    class ErrorController extends AppController
+    {
+        protected function missingWidget(MissingWidgetException $error)
+        {
+            // You can prepare additional template context or trap errors.
+        }
+    }
+
+.. versionadded:: 5.2.0
+    Exception specific controller methods and templates were added.
+
 .. _custom-exceptionrenderer:
 
 Custom ExceptionRenderer