Merge branch '5.next' into 6.x

Author: ADmad

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

@@ -5,6 +5,14 @@ The 5.3.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.
 
+Upgrade to PHP 8.2
+==================
+
+If you are not running on **PHP 8.2 or higher**, you will need to upgrade PHP before updating CakePHP.
+
+.. note::
+    CakePHP 5.3 requires **a minimum of PHP 8.2**.
+
 Behavior Changes
 ================
 
@@ -17,14 +25,32 @@ View
 Deprecations
 ============
 
+Http
+----
+
+- Using `$request->getParam('?')` to get the query params is deprecated.
+  Use `$request->getQueryParams()` instead.
+
 ORM
 ---
 
 - Calling behavior methods on table instances is now deprecated. To call
   a method of an attached behavior you need to use
   ``$table->getBehavior('Sluggable')->slugify()`` instead of ``$table->slugify()``.
+- ``EntityTrait::isEmpty()`` is deprecated. Use ``hasValue()`` instead.
 
 New Features
 ============
 
-TODO
+Routing
+-------
+
+- ``EntityRoute`` now handles enum value conversions. This enables you to use
+  enum backed properties as route parameters. When an enum backed property is
+  used in routing, the enum's ``value`` or ``name`` will be used.
+
+Validation
+----------
+
+- ``ipOrRange()`` validation has has been added to check for an IP or a range (subnet).
+

en/development/testing.rst

@@ -510,7 +510,7 @@ An example table would be::
               ],
           ],
        ],
-       // More tables.
+       // More tables
     ];
 
 The options available to ``columns``, ``indexes`` and ``constraints`` match the
@@ -536,36 +536,6 @@ To load a SQL dump file you can use the following::
 At the beginning of each test run ``SchemaLoader`` will drop all tables in the
 connection and rebuild tables based on the provided schema file.
 
-.. _fixture-state-management:
-
-Fixture State Managers
-----------------------
-
-By default CakePHP resets fixture state at the end of each test by truncating
-all the tables in the database. This operation can become expensive as your
-application grows. By using ``TransactionStrategy`` each test method will be run
-inside a transaction that is rolled back at the end of the test. This can yield
-improved performance but requires your tests not heavily rely on static fixture
-data, as auto-increment values are not reset before each test.
-
-The fixture state management strategy can be defined within the test case::
-
-    use Cake\TestSuite\TestCase;
-    use Cake\TestSuite\Fixture\FixtureStrategyInterface;
-    use Cake\TestSuite\Fixture\TransactionStrategy;
-
-    class ArticlesTableTest extends TestCase
-    {
-        /**
-         * Create the fixtures strategy used for this test case.
-         * You can use a base class/trait to change multiple classes.
-         */
-        protected function getFixtureStrategy(): FixtureStrategyInterface
-        {
-            return new TransactionStrategy();
-        }
-    }
-
 Creating Fixtures
 -----------------
 
@@ -744,6 +714,46 @@ You can also directly include fixtures by FQCN::
     }
 
 
+
+.. _fixture-state-management:
+
+Fixture State Managers
+----------------------
+
+By default CakePHP resets fixture state at the end of each test by truncating
+all the tables in the database. This operation can become expensive as your
+application grows. By using ``TransactionStrategy`` each test method will be run
+inside a transaction that is rolled back at the end of the test. This can yield
+improved performance but requires your tests not heavily rely on static fixture
+data, as auto-increment values are not reset before each test.
+
+The fixture state management strategy can be defined within the test case::
+
+    use Cake\TestSuite\TestCase;
+    use Cake\TestSuite\Fixture\FixtureStrategyInterface;
+    use Cake\TestSuite\Fixture\TransactionStrategy;
+
+    class ArticlesTableTest extends TestCase
+    {
+        /**
+         * Create the fixtures strategy used for this test case.
+         * You can use a base class/trait to change multiple classes.
+         */
+        protected function getFixtureStrategy(): FixtureStrategyInterface
+        {
+            return new TransactionStrategy();
+        }
+    }
+
+To switch out the general default strategy, use Configure key ``TestSuite.fixtureStrategy`` in your ``app.php``::
+
+    'TestSuite' => [
+        'fixtureStrategy' => \Cake\TestSuite\Fixture\TransactionStrategy::class,
+    ],
+
+
+The recommended strategy for medium and large applications is the ``TransactionStrategy``, as using rollbacks to undo changes from tests is simpler to maintain, and reduces the chances of cross-contamination and side-effects between tests.
+
 Fixture Factories
 -----------------
 

en/orm/behaviors/counter-cache.rst

@@ -173,13 +173,13 @@ for all records of one or all configured associations in batches. This can be us
 for example, to update the counter cache after importing data directly into the database.::
 
     // Update the counter cache for all configured associations
-    $table->updateCounterCache();
+    $table->getBehavior('CounterCache')->updateCounterCache();
 
     // Update the counter cache for a specific association, 200 records per batch
-    $table->updateCounterCache('Articles', 200);
+    $table->getBehavior('CounterCache')->updateCounterCache('Articles', 200);
 
     // Update only the first page of records
-    $table->updateCounterCache('Articles', page: 1);
+    $table->getBehavior('CounterCache')->updateCounterCache('Articles', page: 1);
 
 .. versionadded:: 5.2.0
 

en/orm/behaviors/timestamp.rst

@@ -65,10 +65,10 @@ changing any other properties. This is sometimes referred to as 'touching'
 a record. In CakePHP you can use the ``touch()`` method to do exactly this::
 
     // Touch based on the Model.beforeSave event.
-    $articles->touch($article);
+    $articles->getBehavior('Timestamp')->touch($article);
 
     // Touch based on a specific event.
-    $orders->touch($order, 'Orders.completed');
+    $orders->getBehavior('Timestamp')->touch($order, 'Orders.completed');
 
 After you have saved the entity, the field is updated.
 

en/orm/behaviors/translate.rst

@@ -350,7 +350,7 @@ modifying the application's state. For these scenarios use the behavior's
     I18n::setLocale('en'); // reset for illustration
 
     // specific locale.
-    $this->Articles->setLocale('es');
+    $this->Articles->getBehavior('Translate')->setLocale('es');
 
     $article = $this->Articles->get(12);
     echo $article->title; // Echoes 'Un Artículo', yay piece of cake!
@@ -361,8 +361,8 @@ to call the method on each table, for example::
 
     I18n::setLocale('en'); // reset for illustration
 
-    $this->Articles->setLocale('es');
-    $this->Articles->Categories->setLocale('es');
+    $this->Articles->getBehavior('Translate')->setLocale('es');
+    $this->Articles->Categories->getBehavior('Translate')->setLocale('es');
 
     $data = $this->Articles->find('all', contain: ['Categories']);
 
@@ -375,9 +375,9 @@ Querying Translated Fields
 TranslateBehavior does not substitute find conditions by default. You need to use
 ``translationField()`` method to compose find conditions on translated fields::
 
-    $this->Articles->setLocale('es');
+    $this->Articles->getBehavior('Translate')->setLocale('es');
     $query = $this->Articles->find()->where([
-        $this->Articles->translationField('title') => 'Otro Título'
+        $this->Articles->getBehavior('Translate')->translationField('title') => 'Otro Título'
     ]);
 
 Saving in Another Language
@@ -442,7 +442,7 @@ default language directly to the table::
 
     $article->title = 'Mi Primer Artículo';
 
-    $this->Articles->setLocale('es');
+    $this->Articles->getBehavior('Translate')->setLocale('es');
     $this->Articles->save($article);
 
 Setting the language directly in the table is useful when you need to both

en/orm/behaviors/tree.rst

@@ -61,7 +61,7 @@ You can verify it works by getting any row from the table and asking for the
 count of descendants it has::
 
     $node = $categories->get(1);
-    echo $categories->childCount($node);
+    echo $categories->getBehavior('Tree')->childCount($node);
 
 Getting direct descendents
 --------------------------
@@ -179,13 +179,13 @@ having to change their parent::
     $node = $categories->get(5);
 
     // Move the node so it shows up one position up when listing children.
-    $categories->moveUp($node);
+    $categories->getBehavior('Tree')->moveUp($node);
 
     // Move the node to the top of the list inside the same level.
-    $categories->moveUp($node, true);
+    $categories->getBehavior('Tree')->moveUp($node, true);
 
     // Move the node to the bottom.
-    $categories->moveDown($node, true);
+    $categories->getBehavior('Tree')->moveDown($node, true);
 
 Configuration
 =============
@@ -237,12 +237,12 @@ In the previous example, all tree operations will be scoped to only the rows
 having the column ``country_name`` set to 'Brazil'. You can change the scoping
 on the fly by using the 'config' function::
 
-    $this->behaviors()->Tree->setConfig('scope', ['country_name' => 'France']);
+    $this->getBehavior('Tree')->setConfig('scope', ['country_name' => 'France']);
 
 Optionally, you can have a finer grain control of the scope by passing a closure
 as the scope::
 
-    $this->behaviors()->Tree->setConfig('scope', function ($query) {
+    $this->getBehavior('Tree')->setConfig('scope', function ($query) {
         $country = $this->getConfigureContry(); // A made-up function
         return $query->where(['country_name' => $country]);
     });
@@ -311,7 +311,7 @@ is also possible to only delete one node and re-assign all children to the
 immediately superior parent node in the tree::
 
     $aCategory = $categoriesTable->get(10);
-    $categoriesTable->removeFromTree($aCategory);
+    $categoriesTable->getBehavior('Tree')->removeFromTree($aCategory);
     $categoriesTable->delete($aCategory);
 
 All children nodes will be kept and a new parent will be assigned to them.

en/orm/entities.rst

@@ -132,8 +132,7 @@ You can check if fields are defined in your entities with ``has()``::
     $article->has('undefined'); // false
 
 The ``has()`` method will return ``true`` if a field is defined. You can use
-``hasValue()`` to check if a field contains a 'non-empty'
-value::
+``hasValue()`` to check if a field contains a 'non-empty' value::
 
     $article = new Article([
         'title' => 'First post',
@@ -567,7 +566,7 @@ field that should be exposed::
 
     class User extends Entity
     {
-        protected $_virtual = ['full_name'];
+        protected array $_virtual = ['full_name'];
     }
 
 This list can be modified at runtime using the ``setVirtual()`` method::

fr/orm/entities.rst

@@ -136,7 +136,7 @@ Vous pouvez vérifier si des champs sont définis dans vos entities avec
     $article->has('undefined'); // false.
 
 La méthode ``has()`` va renvoyer ``true`` si un champ est défini est a une
-valeur non null. Vous pouvez utiliser ``isEmpty()`` et ``hasValue()`` pour
+valeur non null. Vous pouvez utiliser ``hasValue()`` pour
 vérifier si un champ contient une valeur 'non-empty'::
 
     $article = new Article([
@@ -147,27 +147,21 @@ vérifier si un champ contient une valeur 'non-empty'::
     ]);
     ]);
     $article->has('title'); // true
-    $article->isEmpty('title');  // false
     $article->hasValue('title'); // true
 
     $article->has('user_id'); // true
-    $article->isEmpty('user_id');  // true
     $article->hasValue('user_id'); // false
 
     $article->has('text'); // true
-    $article->isEmpty('text');  // true
     $article->hasValue('text'); // false
 
     $article->has('links'); // true
-    $article->isEmpty('links');  // true
     $article->hasValue('links'); // false
 
     $article->has('text'); // true
-    $article->isEmpty('text');  // true
     $article->hasValue('text'); // false
 
     $article->has('links'); // true
-    $article->isEmpty('links');  // true
     $article->hasValue('links'); // false
 
 Accesseurs & Mutateurs
@@ -600,7 +594,7 @@ doivent être exposés::
 
     class User extends Entity
     {
-        protected $_virtual = ['full_name'];
+        protected array $_virtual = ['full_name'];
     }
 
 Cette liste peut être modifiée à la volée en utilisant la méthode

ja/orm/entities.rst

@@ -109,17 +109,14 @@ CakePHP の ORM を使うためにエンティティークラスを生成する
     $article->has('undefined'); // false.
 
 ``has()`` メソッドは、プロパティが定義されていてヌル以外の値を持つ場合、 ``true`` を返します。
-``isEmpty()`` と ``hasValue()`` を使って、プロパティに '空でない' 値が含まれているかどうかを
+``hasValue()`` を使って、プロパティに '空でない' 値が含まれているかどうかを
 調べることができます。 ::
 
     $article = new Article([
         'title' => 'First post',
         'user_id' => null
     ]);
-    $article->isEmpty('title');  // false
     $article->hasValue('title'); // true
-
-    $article->isEmpty('user_id');  // true
     $article->hasValue('user_id'); // false
 
 アクセサーとミューテーター
@@ -502,7 +499,7 @@ CakePHP では以下のように簡単にできます。 ::
 
     class User extends Entity
     {
-        protected $_virtual = ['full_name'];
+        protected array $_virtual = ['full_name'];
     }
 
 実行時に ``setVirtual()`` を使うことでこのリストを変更できます。 ::

pt/orm/entities.rst

@@ -496,9 +496,7 @@ virtuais que devem ser expostas::
 
     class User extends Entity
     {
-
-        protected $_virtual = ['full_name'];
-
+        protected array $_virtual = ['full_name'];
     }
 
 Esta lista pode ser modificada em tempo de execução usando o método