Merge branch '5.x' into 5.next

ADmad · ADmad · commit d20664cea870 · 2024-03-17T23:21:24.000+05:30
diff --git a/config/conf.py b/config/conf.py
@@ -117,3 +117,7 @@
 """
 
 # todo_include_todos = True
+
+# turn off contents entries for classes/functions
+# generally we add titles for methods and classes instead.
+toc_object_entries = False
diff --git a/en/appendices/5-0-migration-guide.rst b/en/appendices/5-0-migration-guide.rst
@@ -42,7 +42,7 @@ Global
    - MariaDB (10.1 or higher)
    - PostgreSQL (9.6 or higher)
    - Microsoft SQL Server (2012 or higher)
-   - SQLite 3
+   - SQLite 3 (3.16 or higher)
 
 Auth
 ----
@@ -56,6 +56,12 @@ Cache
 - The ``Wincache`` engine was removed. The wincache extension is not supported
   on PHP 8.
 
+Collection
+----------
+
+- ``combine()`` now throws an exception if the key path or group path doesn't exist or contains a null value.
+  This matches the behavior of ``indexBy()`` and ``groupBy()``.
+
 Console
 -------
 
diff --git a/en/appendices/phpunit10.rst b/en/appendices/phpunit10.rst
@@ -21,7 +21,7 @@ New event system
 ----------------
 
 PHPUnit 10 removed the old hook system and introduced a new `Event system
-<https://docs.phpunit.de/en/10.0/extending-phpunit.html#extending-the-test-runner>`_
+<https://docs.phpunit.de/en/10.5/extending-phpunit.html#extending-the-test-runner>`_
 which requires the following code in your ``phpunit.xml`` to be adjusted from::
 
   <extensions>
diff --git a/en/contributing/cakephp-coding-conventions.rst b/en/contributing/cakephp-coding-conventions.rst
@@ -569,6 +569,17 @@ underscore character, for example::
 
     define('LONG_NAMED_CONSTANT', 2);
 
+Enums
+-----
+
+Enum cases are defined in ``CamelCase`` style::
+
+    enum ArticleStatus: string
+    {
+        case Published = 'Y';
+        case NotPublishedYet = 'N';
+    }
+
 Careful when using empty()/isset()
 ==================================
 
diff --git a/en/controllers.rst b/en/controllers.rst
@@ -434,48 +434,39 @@ By using the second parameter you can define a status code for your redirect::
 See the :ref:`redirect-component-events` section for how to redirect out of
 a life-cycle handler.
 
-Forwarding to an Action on the Same Controller
-----------------------------------------------
+Loading Additional Tables/Models
+================================
 
-.. php:method:: setAction($action, $args...)
+.. php:method:: fetchTable(string $alias, array $config = [])
 
-If you need to forward the current action to a different action on the *same*
-controller, you can use ``Controller::setAction()`` to update the request
-object, modify the view template that will be rendered and forward execution to
-the named action::
+The ``fetchTable()`` method comes handy when you need to use an ORM table that is not
+the controller's default one::
 
-    // From a delete action, you can render the updated
-    // list page.
-    $this->setAction('index');
+    // In a controller method.
+    $recentArticles = $this->fetchTable('Articles')->find('all',
+            limit: 5,
+            order: 'Articles.created DESC'
+        )
+        ->all();
 
-Loading Additional Models
-=========================
+.. php:method:: fetchModel(string|null $modelClass = null, string|null $modelType = null)
 
-.. php:method:: fetchModel(string $alias, array $config = [])
+The ``fetchModel()`` method is useful to load non ORM models or ORM tables that
+are not the controller's default::
 
-The ``fetchModel()`` method is useful to load models or ORM tables that
-are not the controller's default. Models retrieved with this method will not be
-set as properties on your controller::
+    // ModelAwareTrait need to be explicity added to your controler first for fetchModel() to work.
+    use ModelAwareTrait;
 
     // Get an ElasticSearch model
     $articles = $this->fetchModel('Articles', 'Elastic');
 
     // Get a webservices model
     $github = $this->fetchModel('GitHub', 'Webservice');
 
-.. versionadded:: 4.5.0
-
-.. php:method:: fetchTable(string $alias, array $config = [])
-
-The ``fetchTable()`` method comes handy when you need to use an ORM table that is not
-the controller's default one::
+    // If you skip the 2nd argument it will by default try to load a ORM table.
+    $authors = $this->fetchModel('Authors');
 
-    // In a controller method.
-    $recentArticles = $this->fetchTable('Articles')->find('all',
-            limit: 5,
-            order: 'Articles.created DESC'
-        )
-        ->all();
+.. versionadded:: 4.5.0
 
 Paginating a Model
 ==================
diff --git a/en/controllers/pagination.rst b/en/controllers/pagination.rst
@@ -269,7 +269,7 @@ Using a paginator class directly
 You can also use a paginator directly.::
 
         // Create a paginator
-        $paginator = new \Cake\Datasource\Paginator\Paginator();
+        $paginator = new \Cake\Datasource\Paginator\NumericPaginator();
 
         // Paginate the model
         $results = $paginator->paginate(
diff --git a/en/development/dependency-injection.rst b/en/development/dependency-injection.rst
@@ -292,15 +292,11 @@ Auto Wiring is turned off by default. To enable it::
     // In src/Application.php
     public function services(ContainerInterface $container): void
     {
-        $container->add(\Cake\Controller\ComponentRegistry::class);
         $container->delegate(
             new \League\Container\ReflectionContainer()
         );
     }
 
-The ``$container->add(\Cake\Controller\ComponentRegistry::class);`` is needed to
-fix a cyclic dependency between ``ComponentRegistry`` and ``Controller``.
-
 While your dependencies will now be resolved automatically, this approach will
 not cache resolutions which can be detrimental to performance. To enable
 caching::
diff --git a/en/development/sessions.rst b/en/development/sessions.rst
@@ -15,8 +15,10 @@ Session Configuration
 Session configuration is generally defined in **/config/app.php**. The available
 options are:
 
-* ``Session.timeout`` - The number of *minutes* before CakePHP's session
-  handler expires the session.
+* ``Session.timeout`` - The number of *minutes* a session can remain 'idle'. If
+  no request is received for ``timeout`` minutes, CakePHP's session
+  handler will expire the session. You can set this option to ``0`` to disable
+  server side idle timeouts.
 
 * ``Session.defaults`` - Allows you to use the built-in default session
   configurations as a base for your session configuration. See below for the
@@ -49,7 +51,7 @@ this::
         ]
     ]);
 
-As of v4.0 CakePHP also sets the `SameSite <https://owasp.org/www-community/SameSite>`__ attribute to ``Lax``
+CakePHP also sets the `SameSite <https://owasp.org/www-community/SameSite>`__ attribute to ``Lax``
 by default for session cookies, which helps protect against CSRF attacks.
 You can change the default value by setting ``session.cookie_samesite`` php.ini config::
 
@@ -80,8 +82,7 @@ configured using::
     Configure::write('Session', [
         'defaults' => 'php',
         'ini' => [
-            // Invalidate the cookie after 30 minutes without visiting
-            // any page on the site.
+            // Invalidate the cookie after 30 minutes
             'session.cookie_lifetime' => 1800
         ]
     ]);
@@ -93,7 +94,7 @@ client reports, you should use ``Session.timeout``.
 
 Please note that ``Session.timeout`` corresponds to the total time of
 inactivity for a user (i.e. the time without visiting any page where the session
-is used), and does not limit the total amount of minutes a user can stay
+is used), and does not limit the total amount of minutes a user can stay active
 on the site.
 
 Built-in Session Handlers & Configuration
diff --git a/en/development/testing.rst b/en/development/testing.rst
@@ -1680,14 +1680,13 @@ correctly by the ``adjust()`` method in our component. We create the file
         public function setUp(): void
         {
             parent::setUp();
-            // Setup our component and fake test controller
+            // Setup our component and provide it a basic controller.
+            // If your component relies on Application features, use AppController.
             $request = new ServerRequest();
             $response = new Response();
-            $this->controller = $this->getMockBuilder('Cake\Controller\Controller')
-                ->setConstructorArgs([$request, $response])
-                ->setMethods(null)
-                ->getMock();
+            $this->controller = new Controller($request);
             $registry = new ComponentRegistry($this->controller);
+
             $this->component = new PagematronComponent($registry);
             $event = new Event('Controller.startup', $this->controller);
             $this->component->startup($event);
diff --git a/en/intro/conventions.rst b/en/intro/conventions.rst
@@ -114,6 +114,10 @@ Entity class names are singular CamelCased and have no suffix. ``User``,
 matching the ``users``, ``menu_links`` and ``user_favorite_pages``
 tables respectively.
 
+Enum class names should use a ``{Entity}{Column}`` convention, and enum cases
+should use CamelCased names.
+
+
 View Conventions
 ================
 
diff --git a/en/orm.rst b/en/orm.rst
@@ -59,7 +59,7 @@ In other contexts, you can use the ``LocatorAwareTrait`` which add accessor meth
 
     public function someMethod()
     {
-        $articles = $this->getTableLocator()->get('Articles');
+        $articles = $this->fetchTable('Articles');
         // more code.
     }
 
@@ -88,7 +88,7 @@ load entities from the database we'll get instances of our new Article class::
 
     use Cake\ORM\Locator\LocatorAwareTrait;
 
-    $articles = $this->getTableLocator()->get('Articles');
+    $articles = $this->fetchTable('Articles');
     $resultset = $articles->find()->all();
 
     foreach ($resultset as $row) {
@@ -113,11 +113,11 @@ More Information
     orm/query-builder
     orm/table-objects
     orm/entities
+    orm/associations
     orm/retrieving-data-and-resultsets
     orm/validation
     orm/saving-data
     orm/deleting-data
-    orm/associations
     orm/behaviors
     orm/schema-system
     console-commands/schema-cache
diff --git a/en/orm/behaviors.rst b/en/orm/behaviors.rst
@@ -222,7 +222,7 @@ these cases you can use the ``implementedFinders`` configuration key to rename
 or exclude finder methods. For example if we wanted to rename our ``find(slug)``
 method we could do the following::
 
-    protected $_defaultConfig = [
+    protected array $_defaultConfig = [
         'implementedFinders' => [
             'slugged' => 'findSlug',
         ]
diff --git a/en/orm/database-basics.rst b/en/orm/database-basics.rst
@@ -479,10 +479,16 @@ Where ``ArticleStatus`` contains something like::
 
     enum ArticleStatus: string
     {
-        case PUBLISHED = 'Y';
-        case UNPUBLISHED = 'N';
+        case Published = 'Y';
+        case Unpublished = 'N';
     }
 
+CakePHP recommends a few conventions for enums:
+
+- Enum classnames should follow ``{Entity}{ColumnName}`` style to enable
+  detection while running bake and to aid with project consistency.
+- Enum cases should use CamelCase style.
+
 .. _adding-custom-database-types:
 
 Adding Custom Types
diff --git a/en/orm/query-builder.rst b/en/orm/query-builder.rst
@@ -97,6 +97,7 @@ The easiest way is to either call the ``all()`` or ``toList()`` methods::
     $resultsArray = $articles
         ->find()
         ->where(['id >' => 1])
+        ->all()
         ->toList();
 
     foreach ($resultsArray as $article) {
@@ -591,27 +592,6 @@ Also, it's possible to create the simple variant by passing a value to ``case()`
 
     # CASE published WHEN true THEN 'Y' ELSE 'N' END;
 
-Prior to 4.3.0, you would need to use::
-
-    $query = $articles->find();
-    $publishedCase = $query->newExpr()
-        ->addCase(
-            $query->newExpr()->add(['published' => 'Y']),
-            1,
-            'integer'
-        );
-    $unpublishedCase = $query->newExpr()
-        ->addCase(
-            $query->newExpr()->add(['published' => 'N']),
-            1,
-            'integer'
-        );
-
-    $query->select([
-        'number_published' => $query->func()->count($publishedCase),
-        'number_unpublished' => $query->func()->count($unpublishedCase)
-    ]);
-
 The ``addCase`` function can also chain together multiple statements to create
 ``if .. then .. [elseif .. then .. ] [ .. else ]`` logic inside your SQL.
 
@@ -1144,7 +1124,7 @@ use the ``IS`` operator to automatically create the correct expression::
     $query = $categories->find()
         ->where(['parent_id IS' => $parentId]);
 
-The above will create ``parent_id` = :c1`` or ``parent_id IS NULL`` depending on
+The above will generate``parent_id = :c1`` or ``parent_id IS NULL`` depending on
 the type of ``$parentId``
 
 Automatic IS NOT NULL Creation
@@ -1156,7 +1136,7 @@ can use the ``IS NOT`` operator to automatically create the correct expression::
     $query = $categories->find()
         ->where(['parent_id IS NOT' => $parentId]);
 
-The above will create ``parent_id` != :c1`` or ``parent_id IS NOT NULL``
+The above will generate``parent_id != :c1`` or ``parent_id IS NOT NULL``
 depending on the type of ``$parentId``
 
 
diff --git a/en/orm/retrieving-data-and-resultsets.rst b/en/orm/retrieving-data-and-resultsets.rst
@@ -19,7 +19,7 @@ be more complicated than in previous CakePHP versions. There are now various
 ways to inspect the data returned by the ORM.
 
 - ``debug($query)`` Shows the SQL and bound parameters, does not show results.
-- ``sql($query)`` Shows the final rendered SQL, but only when having DebugKit installed.
+- ``sql($query)`` Shows the final rendered SQL when DebugKit is installed.
 - ``debug($query->all())`` Shows the ResultSet properties (not the results).
 - ``debug($query->toList())`` Show results in an array.
 - ``debug(iterator_to_array($query))`` Shows query results in an array format.
@@ -136,8 +136,7 @@ execute until you start fetching rows, convert it to an array, or when the
         ->contain(['Comments', 'Authors'])
         ->limit(10);
 
-You can also provide many commonly used options to ``find()``. This can help
-with testing as there are fewer methods to mock::
+You can also provide many commonly used options to ``find()``::
 
     // In a controller or table method.
     $query = $articles->find('all',
diff --git a/en/orm/saving-data.rst b/en/orm/saving-data.rst
diff --git a/en/orm/table-objects.rst b/en/orm/table-objects.rst
diff --git a/en/orm/validation.rst b/en/orm/validation.rst
diff --git a/es/appendices/phpunit10.rst b/es/appendices/phpunit10.rst
