Merge branch '5.x' into issue/7906

Author: markstory

.github/workflows/ci.yml

@@ -16,7 +16,7 @@ permissions:
 
 jobs:
   build:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     strategy:
       matrix:
         doc-type: ['HTML', 'EPUB', 'PDF']
@@ -33,10 +33,10 @@ jobs:
         python -m pip install --upgrade pip
         pip install -r requirements.txt
 
-    - name: Install packages
-      run: |
-        sudo apt update
-        sudo apt install texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-lang-all
+    - uses: awalsh128/cache-apt-pkgs-action@v1
+      with:
+        packages: texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-lang-all
+        version: ubuntu-24.04
 
     - name: Build Docs
       run: |

Dockerfile

@@ -1,6 +1,6 @@
 FROM debian:bookworm
 
-ENV DEBIAN_FRONTEND noninteractive
+ENV DEBIAN_FRONTEND=noninteractive
 
 LABEL Description="This image is used to create an environment to contribute to the cakephp/docs"
 

config/conf.py

@@ -112,7 +112,7 @@
 epub_tocdepth = 2
 
 rst_epilog = """
-.. |phpversion| replace:: **8.3**
+.. |phpversion| replace:: **8.4**
 .. |minphpversion| replace:: 8.1
 """
 

en/appendices.rst

@@ -4,15 +4,10 @@ Appendices
 Appendices contain information regarding the new features
 introduced in each version and the migration path between versions.
 
-5.x Migration Guide
-===================
-
-.. toctree::
-    :maxdepth: 1
+Migration Guides
+================
 
-    appendices/5-0-upgrade-guide
-    appendices/5-0-migration-guide
-    appendices/5-1-migration-guide
+:doc:`appendices/migration-guides`
 
 Backwards Compatibility Shimming
 ================================

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

@@ -47,8 +47,8 @@ Global
 Auth
 ----
 
-- `Auth` has been removed. Use the `cakephp/authentication <https://book.cakephp.org/authentication/2/en/index.html>`__ and
-  `cakephp/authorization <https://book.cakephp.org/authorization/2/en/index.html>`__ plugins instead.
+- `Auth` has been removed. Use the `cakephp/authentication <https://book.cakephp.org/authentication/3/en/index.html>`__ and
+  `cakephp/authorization <https://book.cakephp.org/authorization/3/en/index.html>`__ plugins instead.
 
 Cache
 -----

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