5.2 migration guide

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,95 @@
+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.
+
+New Features
+============
+
+- ``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.
+
+Deprecations
+============
+
+Console
+-------
+
+- ``Arguments::getMultipleOption()`` is deprecated. Use ``getArrayOption()``
+  instead.
+
+
+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
+--------
+
+- ``JsonType::setDecodingOptions()``  was added. This method lets you define the
+  bitmask options used by ``json_encode()`` calls.
+- 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``.
+
+ORM
+---
+
+- ``CounterCacheBehavior::updateCounterCache()`` has been addded. This method
+  allows you to update the counter cache values for all records of the configured
+  associations.
+
+Error
+-----
+
+- Custom exceptions can have specific error handling logic defined in
+  ``ErrorController``.

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

en/orm/behaviors/counter-cache.rst

@@ -162,3 +162,28 @@ with the same code as described above.::
     ]);
 
 Finally clear all caches with ``bin/cake cache clear_all`` and try it out.
+
+Manually updating counter caches
+================================
+
+.. php:method:: updateCounterCache(?string $assocName = null, int $limit = 100, ?int $page = null): void
+
+The ``updateCounterCache()`` method allows you to update the counter cache values
+for all records of one or all configured associations in batches. This can be useful,
+for example, to update the counter cache after importing data directly into the database.::
+
+    // Update the counter cache for all configured associations
+    $table->updateCounterCache();
+
+    // Update the counter cache for a specific association, 200 records per batch
+    $table->updateCounterCache('Articles', 200);
+
+    // Update only the first page of records
+    $table->updateCounterCache('Articles', page: 1);
+
+.. versionadded:: 5.2.0
+
+.. note::
+
+    This methods won't update the counter cache values for fields which are
+    configured to use a closure to get the count value.

en/orm/database-basics.rst

@@ -353,6 +353,9 @@ uuid
 binaryuuid
     Maps to the UUID type if the database provides one, otherwise this will
     generate a ``BINARY(16)`` column
+nativeuuid
+    Maps to the UUID type in MySQL with MariaDb. In all other databases,
+    ``nativeuuid`` is an alias for ``uuid``.
 integer
     Maps to the ``INTEGER`` type provided by the database. BIT is not yet supported
     at this moment.
@@ -423,6 +426,9 @@ handles, and generate file handles when reading data.
    The ``geometry``, ``point``, ``linestring``, and ``polygon`` types were
    added.
 
+.. versionchanged:: 5.2.0
+    The ``nativeuuid`` type was added.
+
 .. _datetime-type:
 
 DateTime Type

en/views/helpers.rst

@@ -123,7 +123,6 @@ your helper requires. For example::
          * @var array<string, mixed>
          */
         protected array $_defaultConfig = [
-            'errorClass' => 'error',
             'templates' => [
                 'label' => '<label for="{{for}}">{{content}}</label>',
             ],
@@ -134,8 +133,8 @@ Any configuration provided to your helper's constructor will be merged with the
 default values during construction and the merged data will be set to
 ``_config``. You can use the ``getConfig()`` method to read runtime configuration::
 
-    // Read the errorClass config option.
-    $class = $this->Awesome->getConfig('errorClass');
+    // Read the autoSetCustomValidity config option.
+    $class = $this->Awesome->getConfig('autoSetCustomValidity');
 
 Using helper configuration allows you to declaratively configure your helpers and
 keep configuration logic out of your controller actions. If you have

es/views/helpers.rst

@@ -114,7 +114,6 @@ Por defecto, todas las opciones de configuración se fusionarán con la propieda
          * @var array<string, mixed>
          */
         protected $_defaultConfig = [
-            'errorClass' => 'error',
             'templates' => [
                 'label' => '<label for="{{for}}">{{content}}</label>',
             ],
@@ -123,8 +122,8 @@ Por defecto, todas las opciones de configuración se fusionarán con la propieda
 
 Cualquier configuración proporcionada al constructor de tu helper se fusionará con los valores por defecto durante la construcción y los datos fusionados se establecerán en ``_config``. Puedes utilizar el método ``getConfig()`` para leer la configuración en tiempo de ejecución::
 
-    // Lee la opción de configuración errorClass.
-    $class = $this->Awesome->getConfig('errorClass');
+    // Lee la opción de configuración autoSetCustomValidity .
+    $class = $this->Awesome->getConfig('autoSetCustomValidity ');
 
 Usar la configuración del helper te permite configurar declarativamente tus helpers y mantener la lógica de configuración fuera de las acciones de tu controlador. Si tienes opciones de configuración que no se pueden incluir como parte de una declaración de clase, puedes configurarlas en el callback ``beforeRender`` de tu controlador::
 

fr/views/helpers.rst

@@ -144,7 +144,6 @@ défaut de toute configuration dont votre helper a besoin. Par exemple::
         use StringTemplateTrait;
 
         protected $_defaultConfig = [
-            'errorClass' => 'error',
             'templates' => [
                 'label' => '<label for="{{for}}">{{content}}</label>',
             ],
@@ -156,8 +155,8 @@ les valeurs par défaut pendant la construction et les données fusionnées sero
 définies à ``_config``. Vous pouvez utiliser la méthode ``config()`` pour lire
 la configuration actuelle::
 
-    // Lit l'option de config errorClass.
-    $class = $this->Awesome->config('errorClass');
+    // Lit l'option de config autoSetCustomValidity .
+    $class = $this->Awesome->config('autoSetCustomValidity ');
 
 L'utilisation de la configuration du helper vous permet de configurer de manière
 déclarative vos helpers et de garder la logique de configuration en dehors des