Give the ORM docs a read through and fix old content

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

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

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',
         ]

en/orm/query-builder.rst

@@ -591,27 +591,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 +1123,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 +1135,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``
 
 

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',

en/orm/saving-data.rst

@@ -24,7 +24,7 @@ passing it to the ``save()`` method in the ``Table`` class::
 
     use Cake\ORM\Locator\LocatorAwareTrait;
 
-    $articlesTable = $this->getTableLocator()->get('Articles');
+    $articlesTable = $this->fetchTable('Articles');
     $article = $articlesTable->newEmptyEntity();
 
     $article->title = 'A New Article';
@@ -42,7 +42,7 @@ Updating your data is achieved by using the ``save()`` method ::
 
     use Cake\ORM\Locator\LocatorAwareTrait;
 
-    $articlesTable = $this->getTableLocator()->get('Articles');
+    $articlesTable = $this->fetchTable('Articles');
     $article = $articlesTable->get(12); // Return article with id 12
 
     $article->title = 'CakePHP is THE best PHP framework!';
@@ -57,7 +57,7 @@ Saving With Associations
 
 By default the ``save()`` method will also save one level of associations::
 
-    $articlesTable = $this->getTableLocator()->get('Articles');
+    $articlesTable = $this->fetchTable('Articles');
     $author = $articlesTable->Authors->findByUserName('mark')->first();
 
     $article = $articlesTable->newEmptyEntity();
@@ -130,7 +130,7 @@ one or many entities from request data. You can convert a single entity using::
 
     // In a controller
 
-    $articles = $this->getTableLocator()->get('Articles');
+    $articles = $this->fetchTable('Articles');
 
     // Validate and convert to an Entity object
     $entity = $articles->newEntity($this->request->getData());
@@ -169,7 +169,7 @@ associations should be marshalled::
 
     // In a controller
 
-    $articles = $this->getTableLocator()->get('Articles');
+    $articles = $this->fetchTable('Articles');
 
     // New entity with nested associations
     $entity = $articles->newEntity($this->request->getData(), [
@@ -183,7 +183,7 @@ should be marshalled. Alternatively, you can use dot notation for brevity::
 
     // In a controller
 
-    $articles = $this->getTableLocator()->get('Articles');
+    $articles = $this->fetchTable('Articles');
 
     // New entity with nested associations using dot notation
     $entity = $articles->newEntity($this->request->getData(), [
@@ -201,7 +201,7 @@ change the validation set to be used per association::
 
     // In a controller
 
-    $articles = $this->getTableLocator()->get('Articles');
+    $articles = $this->fetchTable('Articles');
 
     // Bypass validation on Tags association and
     // Designate 'signup' validation set for Comments.Users
@@ -325,7 +325,7 @@ When creating forms that create/update multiple records at once you can use
 
     // In a controller.
 
-    $articles = $this->getTableLocator()->get('Articles');
+    $articles = $this->fetchTable('Articles');
     $entities = $articles->newEntities($this->request->getData());
 
 In this situation, the request data for multiple articles should look like::
@@ -371,7 +371,7 @@ keep ids of associated entities::
 
     // In a controller
 
-    $articles = $this->getTableLocator()->get('Articles');
+    $articles = $this->fetchTable('Articles');
     $entity = $articles->newEntity($this->request->getData(), [
         'associated' => [
             'Tags', 'Comments' => [
@@ -405,7 +405,7 @@ persisted. You can merge an array of raw data into an existing entity using the
 
     // In a controller.
 
-    $articles = $this->getTableLocator()->get('Articles');
+    $articles = $this->fetchTable('Articles');
     $article = $articles->get(1);
     $articles->patchEntity($article, $this->request->getData());
     $articles->save($article);
@@ -420,7 +420,7 @@ patching an entity, pass the ``validate`` option as follows::
 
     // In a controller.
 
-    $articles = $this->getTableLocator()->get('Articles');
+    $articles = $this->fetchTable('Articles');
     $article = $articles->get(1);
     $articles->patchEntity($article, $data, ['validate' => false]);
 
@@ -546,7 +546,7 @@ delete for those not in the list::
     // In a controller.
     use Cake\Collection\Collection;
 
-    $comments = $this->getTableLocator()->get('Comments');
+    $comments = $this->fetchTable('Comments');
     $present = (new Collection($entity->comments))->extract('id')->filter()->toList();
     $comments->deleteAll([
         'article_id' => $article->id,
@@ -563,7 +563,7 @@ the original entities array will be removed and not present in the result::
 
     // In a controller.
 
-    $articles = $this->getTableLocator()->get('Articles');
+    $articles = $this->fetchTable('Articles');
     $list = $articles->find('popular')->toList();
     $patched = $articles->patchEntities($list, $this->request->getData());
     foreach ($patched as $entity) {
@@ -725,7 +725,7 @@ using ``newEntity()`` for passing into ``save()``. For example::
 
     // In a controller
 
-    $articles = $this->getTableLocator()->get('Articles');
+    $articles = $this->fetchTable('Articles');
     $article = $articles->newEntity($this->request->getData());
     if ($articles->save($article)) {
         // ...
@@ -742,7 +742,7 @@ and the entity has a primary key value, an 'exists' query will be issued. The
 Once you've loaded some entities you'll probably want to modify them and update
 your database. This is a pretty simple exercise in CakePHP::
 
-    $articles = $this->getTableLocator()->get('Articles');
+    $articles = $this->fetchTable('Articles');
     $article = $articles->find('all')->where(['id' => 2])->first();
 
     $article->title = 'My new title';
@@ -859,7 +859,7 @@ the singular, :ref:`underscored <inflector-methods-summary>` version of the asso
         ],
     ];
 
-    $articles = $this->getTableLocator()->get('Articles');
+    $articles = $this->fetchTable('Articles');
     $article = $articles->newEntity($data, [
         'associated' => ['Users']
     ]);
@@ -881,7 +881,7 @@ singular, :ref:`underscored <inflector-methods-summary>` version of the associat
         ],
     ];
 
-    $users = $this->getTableLocator()->get('Users');
+    $users = $this->fetchTable('Users');
     $user = $users->newEntity($data, [
         'associated' => ['Profiles']
     ]);
@@ -902,7 +902,7 @@ plural, :ref:`underscored <inflector-methods-summary>` version of the associatio
         ]
     ];
 
-    $articles = $this->getTableLocator()->get('Articles');
+    $articles = $this->fetchTable('Articles');
     $article = $articles->newEntity($data, [
         'associated' => ['Comments']
     ]);
@@ -954,7 +954,7 @@ the plural, :ref:`underscored <inflector-methods-summary>` version of the associ
         ]
     ];
 
-    $articles = $this->getTableLocator()->get('Articles');
+    $articles = $this->fetchTable('Articles');
     $article = $articles->newEntity($data, [
         'associated' => ['Tags']
     ]);
@@ -1039,7 +1039,7 @@ The example above will only work if the property ``_joinData`` is already a
 reference to a Join Table Entity. If you don't already have a ``_joinData``
 entity, you can create one using ``newEntity()``::
 
-    $coursesMembershipsTable = $this->getTableLocator()->get('CoursesMemberships');
+    $coursesMembershipsTable = $this->fetchTable('CoursesMemberships');
     $student->courses[0]->_joinData = $coursesMembershipsTable->newEntity([
         'grade' => 80.12,
         'days_attended' => 30
@@ -1217,7 +1217,7 @@ be an array of entities created using ``newEntities()`` / ``patchEntities()``.
         ],
     ];
 
-    $articles = $this->getTableLocator()->get('Articles');
+    $articles = $this->fetchTable('Articles');
     $entities = $articles->newEntities($data);
     $result = $articles->saveMany($entities);
 

en/orm/table-objects.rst

@@ -96,7 +96,7 @@ can do this by using the ``TableLocator`` class::
 
     // In a controller
 
-    $articles = $this->getTableLocator()->get('Articles');
+    $articles = $this->fetchTable('Articles');
 
 ``TableLocator`` provides the various dependencies for constructing
 a table, and maintains a registry of all the constructed table instances making
@@ -109,10 +109,10 @@ being triggered as a default class is used instead of your actual class. To
 correctly load plugin table classes use the following::
 
     // Plugin table
-    $articlesTable = $this->getTableLocator()->get('PluginName.Articles');
+    $articlesTable = $this->fetchTable('PluginName.Articles');
 
     // Vendor prefixed plugin table
-    $articlesTable = $this->getTableLocator()->get('VendorName/PluginName.Articles');
+    $articlesTable = $this->fetchTable('VendorName/PluginName.Articles');
 
 .. _table-callbacks:
 

en/orm/validation.rst

@@ -269,14 +269,14 @@ network.
 
 These types of rules are often referred to as 'domain rules' or 'application
 rules'. CakePHP exposes this concept through 'RulesCheckers' which are applied
-before entities are persisted. Some example domain rules are:
+before entities are persisted. Some example application rules are:
 
 * Ensuring email uniqueness
 * State transitions or workflow steps, for example, updating an invoice's status.
 * Preventing the modification of soft deleted items.
 * Enforcing usage/rate limit caps.
 
-Domain rules are checked when calling the Table ``save()`` and ``delete()`` methods.
+Application rules are checked when calling the Table ``save()`` and ``delete()`` methods.
 
 .. _creating-a-rules-checker: