Merge branch '5.x' into 5.next

Author: ADmad

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

@@ -227,6 +227,29 @@ ORM
   ``$this->getSchema()`` inside the ``initialize()`` method.
 - ``SaveOptionsBuilder`` has been removed. Use a normal array for options instead.
 
+Known Issues
+------------
+
+**Memory usage with large result sets**
+
+Compared to CakePHP 4.x, when working with large data sets (especially when
+calling collection methods like ``extract()`` on the result set), you may encounter
+high memory usage due to the entire result set being buffered in memory.
+
+You can work around this issue by disabling results buffering for the query::
+
+    $results = $articles->find()
+        ->disableBufferedResults()
+        ->all();
+
+Depending on your use case, you may also consider using disabling hydration::
+
+    $results = $articles->find()
+        ->disableHydration()
+        ->all();
+
+The above will disable creation of entity objects and return rows as arrays instead.
+
 Routing
 -------
 

en/controllers.rst

@@ -254,7 +254,7 @@ have called ``Controller::render()``, CakePHP will not try to re-render the view
     {
         public function my_action()
         {
-            $this->render('custom_file');
+            return $this->render('custom_file');
         }
     }
 
@@ -271,7 +271,7 @@ For example::
     {
         public function myAction()
         {
-            $this->render('Users.UserDetails/custom_file');
+            return $this->render('Users.UserDetails/custom_file');
         }
     }
 

en/controllers/components.rst

@@ -190,6 +190,8 @@ as constructor parameters::
 
     class SsoComponent extends Component
     {
+        private Users $users;
+
         public function __construct(
             ComponentRegistry $registry,
             array $config = [],

en/core-libraries/collections.rst

@@ -265,8 +265,8 @@ data from paginated services::
 
     $allPagesItems = $items->toList();
 
-If you are using PHP 5.5+, you can use the ``yield`` keyword inside ``unfold()``
-to return as many elements for each item in the collection as you may need::
+You can use the ``yield`` keyword inside ``unfold()``to return as
+many elements for each item in the collection as you may need::
 
     $oddNumbers = [1, 3, 5, 7];
     $collection = new Collection($oddNumbers);
@@ -1187,7 +1187,6 @@ Making Collections Rewindable
 The ``buffered()`` method is also useful for converting non-rewindable iterators
 into collections that can be iterated more than once::
 
-    // In PHP 5.5+
     public function results()
     {
         ...

en/core-libraries/time.rst

@@ -118,7 +118,7 @@ addition of their components::
     $time = DateTime::create(2021, 1, 31, 22, 11, 30);
     $newTime = $time->subDays(5)
         ->addHours(-2)
-        ->addMonth(1);
+        ->addMonths(1);
     // Outputs '2/26/21, 8:11 PM'
     echo $newTime;
 
@@ -359,7 +359,7 @@ You can also get the date range for a quarter::
     $time = new DateTime('2021-01-31');
     $range = $time->toQuarterRange();
     // Outputs ['2021-01-01', '2021-03-31']
-    
+
     $time = new DateTime('2021-12-25');
     $range = $time->toQuarterRange();
     // Outputs ['2021-10-01', '2021-12-31']

en/orm/behaviors/tree.rst

@@ -18,6 +18,7 @@ The TreeBehavior helps you maintain a hierarchical data structure in the
 database that can be queried without much overhead and helps reconstruct the
 tree data for finding and displaying processes.
 
+
 Requirements
 ============
 
@@ -31,6 +32,16 @@ You can configure the name of those fields should you need to customize them.
 More information on the meaning of the fields and how they are used can be found
 in this article describing the `MPTT logic <https://www.sitepoint.com/hierarchical-data-database-2/>`_
 
+.. warning::
+
+    The TreeBehavior is not safe for concurrent write operations.
+    Simultaneous requests that modify tree-structured data
+    (e.g., insertions, deletions, or moves) can lead to corruption of the
+    ``lft`` and ``rght`` values.
+    
+    To prevent this, a locking mechanism like a
+    `Semaphore <https://www.php.net/manual/en/book.sem.php>`_ should be used.
+
 .. warning::
 
     The TreeBehavior does not support composite primary keys at this point in

en/orm/query-builder.rst

@@ -1881,10 +1881,11 @@ named windows using the ``window()`` method::
 Common Table Expressions
 ------------------------
 
-Common Table Expressions or CTE are useful when building reporting queries where
-you need to compose the results of several smaller query results together. They
-can serve a similar purpose to database views or subquery results. Common Table
-Expressions differ from derived tables and views in a couple ways:
+`Common Table Expressions or CTE <https://en.wikipedia.org/wiki/Hierarchical_and_recursive_queries_in_SQL#Common_table_expression>`__
+are useful when building reporting queries where you need to compose the results
+of several smaller query results together. They can serve a similar purpose
+to database views or subquery results. Common Table Expressions differ from
+derived tables and views in a couple ways:
 
 #. Unlike views, you don't have to maintain schema for common table expressions.
    The schema is implicitly based on the result set of the table expression.

en/orm/retrieving-data-and-resultsets.rst

@@ -981,6 +981,26 @@ The :doc:`/core-libraries/collections` chapter has more detail on what can be
 done with result sets using the collections features. The :ref:`format-results`
 section show how you can add calculated fields, or replace the result set.
 
+.. warning::
+
+    When working with large data sets (especially when calling collection methods
+    like ``extract()`` on the result set), you may encounter high memory usage
+    due to the entire result set being buffered in memory.
+
+    You can work around this issue by disabling results buffering for the query::
+
+        $results = $articles->find()
+            ->disableBufferedResults()
+            ->all();
+
+    Depending on your use case, you may also consider using disabling hydration::
+
+        $results = $articles->find()
+            ->disableHydration()
+            ->all();
+
+    The above will disable creation of entity objects and return rows as arrays instead.
+
 Getting the First & Last Record From a ResultSet
 ------------------------------------------------
 

en/tutorials-and-examples.rst

@@ -4,11 +4,6 @@ Tutorials & Examples
 In this section, you can walk through typical CakePHP applications
 to see how all of the pieces come together.
 
-Alternatively, you can refer to the non-official CakePHP plugin repository
-`CakePackages <https://plugins.cakephp.org/>`_ and the
-`Bakery <https://bakery.cakephp.org/>`_ for existing applications
-and components.
-
 .. toctree::
     :maxdepth: 1
 

en/tutorials-and-examples/cms/installation.rst

@@ -45,7 +45,7 @@ in the **cms** directory of the current working directory:
 
 .. code-block:: console
 
-    php composer.phar create-project --prefer-dist cakephp/app:5 cms
+    php composer.phar create-project cakephp/app:5 cms
 
 If you downloaded and ran the `Composer Windows Installer
 <https://getcomposer.org/Composer-Setup.exe>`_, then type the following line in
@@ -54,7 +54,7 @@ C:\\wamp\\www\\dev):
 
 .. code-block:: console
 
-    composer self-update && composer create-project --prefer-dist cakephp/app:5.* cms
+    composer self-update && composer create-project cakephp/app:5.* cms
 
 The advantage to using Composer is that it will automatically complete some
 important set up tasks, such as setting the correct file permissions and