diff --git a/config/conf.py b/config/conf.py index fd4d8c7989..5471b97e9c 100644 --- a/config/conf.py +++ b/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 = [] diff --git a/en/appendices/5-2-migration-guide.rst b/en/appendices/5-2-migration-guide.rst new file mode 100644 index 0000000000..cea94aebc1 --- /dev/null +++ b/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``. diff --git a/en/appendices/migration-guides.rst b/en/appendices/migration-guides.rst index 4c993cde10..2a86606039 100644 --- a/en/appendices/migration-guides.rst +++ b/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 diff --git a/en/console-commands.rst b/en/console-commands.rst index 77c0a10c8b..c40f966c9c 100644 --- a/en/console-commands.rst +++ b/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 diff --git a/en/console-commands/commands.rst b/en/console-commands/commands.rst index 429a048f22..9493a24b5c 100644 --- a/en/console-commands/commands.rst +++ b/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 =================== diff --git a/en/console-commands/counter-cache.rst b/en/console-commands/counter-cache.rst new file mode 100644 index 0000000000..cc50932bcf --- /dev/null +++ b/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 diff --git a/en/console-commands/option-parsers.rst b/en/console-commands/option-parsers.rst index be19eb79a7..c99424bf79 100644 --- a/en/console-commands/option-parsers.rst +++ b/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 ----------------------- diff --git a/en/console-commands/schema-cache.rst b/en/console-commands/schema-cache.rst index 90a24b690a..df891ab6a5 100644 --- a/en/console-commands/schema-cache.rst +++ b/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: diff --git a/en/controllers/components/form-protection.rst b/en/controllers/components/form-protection.rst index d81e1027b5..364f52162a 100644 --- a/en/controllers/components/form-protection.rst +++ b/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. } diff --git a/en/development/errors.rst b/en/development/errors.rst index 7db588815e..12c1a79826 100644 --- a/en/development/errors.rst +++ b/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 diff --git a/en/orm/behaviors/counter-cache.rst b/en/orm/behaviors/counter-cache.rst index ae87db1142..fd633ee6a3 100644 --- a/en/orm/behaviors/counter-cache.rst +++ b/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. diff --git a/en/orm/database-basics.rst b/en/orm/database-basics.rst index d5639e5c85..a88abb75db 100644 --- a/en/orm/database-basics.rst +++ b/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 diff --git a/en/views/helpers.rst b/en/views/helpers.rst index f393807058..ed0d243b89 100644 --- a/en/views/helpers.rst +++ b/en/views/helpers.rst @@ -123,7 +123,6 @@ your helper requires. For example:: * @var array */ protected array $_defaultConfig = [ - 'errorClass' => 'error', 'templates' => [ '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 diff --git a/es/views/helpers.rst b/es/views/helpers.rst index e33bada0c5..5247ffa234 100644 --- a/es/views/helpers.rst +++ b/es/views/helpers.rst @@ -114,7 +114,6 @@ Por defecto, todas las opciones de configuración se fusionarán con la propieda * @var array */ protected $_defaultConfig = [ - 'errorClass' => 'error', 'templates' => [ '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:: diff --git a/fr/views/helpers.rst b/fr/views/helpers.rst index 843bd38e45..befa9a9422 100644 --- a/fr/views/helpers.rst +++ b/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' => '', ], @@ -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 diff --git a/ja/views/helpers.rst b/ja/views/helpers.rst index 059aeab327..9233698771 100644 --- a/ja/views/helpers.rst +++ b/ja/views/helpers.rst @@ -118,7 +118,6 @@ CakePHP やアプリケーションにあるヘルパーを明示的に読み込 use StringTemplateTrait; protected $_defaultConfig = [ - 'errorClass' => 'error', 'templates' => [ 'label' => '', ], @@ -129,8 +128,8 @@ CakePHP やアプリケーションにあるヘルパーを明示的に読み込 マージされたデータは、 ``_config`` に設定されます。 実行時設定を読み取るために ``config()`` メソッドを使用することができます。 :: - // errorClass 設定オプションを読み込み - $class = $this->Awesome->config('errorClass'); + // autoSetCustomValidity 設定オプションを読み込み + $class = $this->Awesome->config('autoSetCustomValidity '); ヘルパー設定を使用すると、宣言的にヘルパーを設定し、コントローラーロジックから設定ロジックを 削除することができます。クラス宣言の一部として組み込むことができない設定オプションがある場合は、