Deprecate TableRegistry.

en/appendices/4-1-migration-guide.rst

@@ -83,6 +83,8 @@ Http
 ORM
 ---
 
+* ``Cake\ORM\TableRegistry`` has been deprecated. Use ``Cake\ORM\Locator\LocatorAwareTrait::getTableLocator()``
+  or ``Cake\Datasource\FactoryLocator::get('Table')`` to get the table locator instance instead.
 * BelongsToMany associations now respect the bindingKey set in the junction table's BelongsTo association.
   Previously, the target table's primary key was always used instead.
 * ``Cake\ORM\AssociationCollection`` no longer lower cases association names

en/console-commands/commands.rst

@@ -340,7 +340,6 @@ Modify your test case to the following snippet of code::
 
     use Cake\Console\Command;
     use Cake\I18n\FrozenTime;
-    use Cake\ORM\TableRegistry;
     use Cake\TestSuite\ConsoleIntegrationTestTrait;
     use Cake\TestSuite\TestCase;
 
@@ -369,7 +368,7 @@ Modify your test case to the following snippet of code::
             $this->exec('update_table Users');
             $this->assertExitCode(Command::CODE_SUCCESS);
 
-            $user = TableRegistry::getTableLocator()->get('Users')->get(1);
+            $user = $this->getTableLocator()->get('Users')->get(1);
             $this->assertSame($user->modified->timestamp, $now->timestamp);
 
             FrozenTime::setTestNow(null);
@@ -451,22 +450,22 @@ incorrect response. Remove the ``testUpdateModified`` method and, add the follow
         $this->exec('update_table Users', ['y']);
         $this->assertExitCode(Command::CODE_SUCCESS);
 
-        $user = TableRegistry::getTableLocator()->get('Users')->get(1);
+        $user = $this->getTableLocator()->get('Users')->get(1);
         $this->assertSame($user->modified->timestamp, $now->timestamp);
 
         FrozenTime::setTestNow(null);
     }
 
     public function testUpdateModifiedUnsure()
     {
-        $user = TableRegistry::getTableLocator()->get('Users')->get(1);
+        $user = $this->getTableLocator()->get('Users')->get(1);
         $original = $user->modified->timestamp;
 
         $this->exec('my_console best_framework', ['n']);
         $this->assertExitCode(Command::CODE_ERROR);
         $this->assertErrorContains('You need to be sure.');
 
-        $user = TableRegistry::getTableLocator()->get('Users')->get(1);
+        $user = $this->getTableLocator()->get('Users')->get(1);
         $this->assertSame($original, $user->timestamp);
     }
 

en/console-commands/repl.rst

@@ -17,7 +17,7 @@ application's models:
 
     bin/cake console
 
-    >>> $articles = Cake\ORM\TableRegistry::getTableLocator()->get('Articles');
+    >>> $articles = Cake\Datasource\FactoryLocator::get('Table')->get('Articles');
     // object(Cake\ORM\Table)(
     //
     // )

en/controllers.rst

@@ -366,17 +366,14 @@ factory method::
         ['ElasticIndexes', 'factory']
     );
 
+The factory can be a callable or instance of ``\Cake\Datasource\Locator\LocatorInterface``.
+
 After registering a table factory, you can use ``loadModel`` to load
 instances::
 
     // In a controller method.
     $this->loadModel('Locations', 'ElasticIndex');
 
-.. note::
-
-    The built-in ORM's TableRegistry is connected by default as the 'Table'
-    provider.
-
 Paginating a Model
 ==================
 

en/controllers/components/pagination.rst

@@ -226,8 +226,8 @@ additional details on how to use the table registry::
         ],
     ];
 
-    // Register an additional table object to allow differentiating in pagination component
-    TableRegistry::getTableLocator()->setConfig('UnpublishedArticles', [
+    // Load an additional table object to allow differentiating in pagination component
+    $this->loadModel('UnpublishedArticles', [
         'className' => 'App\Model\Table\ArticlesTable',
         'table' => 'articles',
         'entityClass' => 'App\Model\Entity\Article',
@@ -240,7 +240,7 @@ additional details on how to use the table registry::
     );
 
     $unpublishedArticles = $this->paginate(
-        TableRegistry::getTableLocator()->get('UnpublishedArticles')->find('all', [
+        $this->UnpublishedArticles->find('all', [
             'scope' => 'unpublished_articles'
         ])->where(['published' => false])
     );

en/core-libraries/events.rst

@@ -229,11 +229,11 @@ a more direct approach and only listen to the event you really need::
 
     // You can create the following before the
     // save operation, ie. config/bootstrap.php
-    use Cake\ORM\TableRegistry;
+    use Cake\Datasource\FactoryLocator;
     // If sending emails
     use Cake\Mailer\Email;
 
-    TableRegistry::getTableLocator()->get('ThirdPartyPlugin.Feedbacks')
+    FactoryLocator::get('Table')->get('ThirdPartyPlugin.Feedbacks')
         ->getEventManager()
         ->on('Model.afterSave', function($event, $entity)
         {

en/development/testing.rst

@@ -612,7 +612,7 @@ use that to retrieve the table name::
         public $import = ['model' => 'Articles'];
     }
 
-Since this uses ``TableRegistry::getTableLocator()->get()``, it also supports plugin syntax.
+It also supports plugin syntax.
 
 You can naturally import your table definition from an existing model/table, but
 have your records defined directly on the fixture as it was shown on previous
@@ -749,7 +749,7 @@ with the following contents::
     namespace App\Test\TestCase\Model\Table;
 
     use App\Model\Table\ArticlesTable;
-    use Cake\ORM\TableRegistry;
+    use Cake\Datasource\FactoryLocator;
     use Cake\TestSuite\TestCase;
 
     class ArticlesTableTest extends TestCase
@@ -771,7 +771,6 @@ now looks like this::
     namespace App\Test\TestCase\Model\Table;
 
     use App\Model\Table\ArticlesTable;
-    use Cake\ORM\TableRegistry;
     use Cake\TestSuite\TestCase;
 
     class ArticlesTableTest extends TestCase
@@ -781,7 +780,7 @@ now looks like this::
         public function setUp(): void
         {
             parent::setUp();
-            $this->Articles = TableRegistry::getTableLocator()->get('Articles');
+            $this->Articles = $this->getTableLocator()->get('Articles');
         }
 
         public function testFindPublished(): void
@@ -826,7 +825,7 @@ avoids issues with reflected properties that normal mocks have::
 
 In your ``tearDown()`` method be sure to remove the mock with::
 
-    TableRegistry::clear();
+    $this->getTableLocator()->clear();
 
 .. _integration-testing:
 
@@ -885,7 +884,6 @@ Create a file named **ArticlesControllerTest.php** in your
 
     namespace App\Test\TestCase\Controller;
 
-    use Cake\ORM\TableRegistry;
     use Cake\TestSuite\IntegrationTestTrait;
     use Cake\TestSuite\TestCase;
 
@@ -932,7 +930,7 @@ Create a file named **ArticlesControllerTest.php** in your
             $this->post('/articles', $data);
 
             $this->assertResponseSuccess();
-            $articles = TableRegistry::getTableLocator()->get('Articles');
+            $articles = $this->getTableLocator()->get('Articles');
             $query = $articles->find()->where(['title' => $data['title']]);
             $this->assertEquals(1, $query->count());
         }
@@ -1617,7 +1615,6 @@ the event data::
 
     use App\Model\Table\OrdersTable;
     use Cake\Event\EventList;
-    use Cake\ORM\TableRegistry;
     use Cake\TestSuite\TestCase;
 
     class OrdersTableTest extends TestCase
@@ -1627,7 +1624,7 @@ the event data::
         public function setUp(): void
         {
             parent::setUp();
-            $this->Orders = TableRegistry::getTableLocator()->get('Orders');
+            $this->Orders = $this->getTableLocator()->get('Orders');
             // enable event tracking
             $this->Orders->getEventManager()->setEventList(new EventList());
         }

en/intro.rst

@@ -35,9 +35,9 @@ and retrieving user photos, finding suggestions for new friends, etc.
 The model objects can be thought of as "Friend", "User", "Comment", or
 "Photo". If we wanted to load some data from our ``users`` table we could do::
 
-    use Cake\ORM\TableRegistry;
+    use Cake\ORM\Locator\LocatorAwareTrait;
 
-    $users = TableRegistry::getTableLocator()->get('Users');
+    $users = $this->getTableLocator()->get('Users');
     $query = $users->find();
     foreach ($query as $row) {
         echo $row->username;
@@ -50,9 +50,9 @@ for table and entity classes that have not yet been defined.
 If we wanted to make a new user and save it (with validation) we would do
 something like::
 
-    use Cake\ORM\TableRegistry;
+    use Cake\ORM\Locator\LocatorAwareTrait;
 
-    $users = TableRegistry::getTableLocator()->get('Users');
+    $users = $this->getTableLocator()->get('Users');
     $user = $users->newEntity(['email' => 'mark@example.com']);
     $users->save($user);
 

en/orm.rst

@@ -27,18 +27,26 @@ Quick Example
 
 To get started you don't have to write any code. If you've followed the :ref:`CakePHP
 conventions for your database tables <model-and-database-conventions>`
-you can just start using the ORM. For example if we wanted to load some data from our ``articles``
-table we could do::
+you can just start using the ORM. For example if we wanted to load some data 
+from our ``articles`` table we could do::
 
-    use Cake\ORM\TableRegistry;
+    use Cake\ORM\Locator\LocatorAwareTrait;
 
-    $articles = TableRegistry::getTableLocator()->get('Articles');
+    public function someMethod()
+    {
+        $articles = $this->getTableLocator->get('Articles');
 
-    $query = $articles->find();
+        $query = $articles->find();
 
-    foreach ($query as $row) {
-        echo $row->title;
+        foreach ($query as $row) {
+            echo $row->title;
+        }
     }
+
+Within a static method you can use the :php:class:`~Cake\\Datasource\\FactoryLocator` 
+to get the table locator::
+
+    $articles = FactoryLocator::get('Table')->get('Articles');
 
 Note that we didn't have to create any code or wire any configuration up.
 The conventions in CakePHP allow us to skip some boilerplate code and allow the
@@ -57,12 +65,11 @@ associations or defining some additional methods we would add the following to
 
 Table classes use the CamelCased version of the table name with the ``Table``
 suffix as the class name. Once your class has been created you get a reference
-to it using the :php:class:`~Cake\\ORM\\Locator\\TableLocator` through :php:class:`~Cake\\ORM\\TableRegistry` as before::
+to it using the :php:class:`~Cake\\ORM\\Locator\\TableLocator` as before::
 
-    use Cake\ORM\TableRegistry;
+    use Cake\ORM\Locator\LocatorAwareTrait;
 
-    // $articles is an instance of our ArticlesTable class.
-    $articles = TableRegistry::getTableLocator()->get('Articles');
+    $articles = $this->getTableLocator()->get('Articles');
 
 Now that we have a concrete table class, we'll probably want to use a concrete
 entity class. Entity classes let you define accessor and mutator methods, define
@@ -81,10 +88,9 @@ Entities use the singular CamelCase version of the table name as their class
 name by default. Now that we have created our entity class, when we
 load entities from the database we'll get instances of our new Article class::
 
-    use Cake\ORM\TableRegistry;
+    use Cake\ORM\Locator\LocatorAwareTrait;
 
-    // $articles is an instance of ArticlesTable.
-    $articles = TableRegistry::getTableLocator()->get('Articles');
+    $articles = $this->getTableLocator()->get('Articles');
     $query = $articles->find();
 
     foreach ($query as $row) {

en/orm/behaviors/tree.rst

@@ -52,8 +52,10 @@ hierarchical data in::
 
 Once added, you can let CakePHP build the internal structure if the table is
 already holding some rows::
-
-    $categories = TableRegistry::getTableLocator()->get('Categories');
+
+    // In a controller
+
+    $categories = $this->getTableLocator()->get('Categories');
     $categories->recover();
 
 You can verify it works by getting any row from the table and asking for the

en/orm/entities.rst

@@ -59,12 +59,12 @@ to store in them::
 
 The preferred way of getting new entities is using the ``newEmptyEntity()`` method from the
 ``Table`` objects::
+
+    use \Cake\ORM\Locator\LocatorAwareTrait;
 
-    use Cake\ORM\TableRegistry;
+    $article = $this->getTableLocator()->newEmptyEntity();
 
-    $article = TableRegistry::getTableLocator()->get('Articles')->newEmptyEntity();
-
-    $article = TableRegistry::getTableLocator()->get('Articles')->newEntity([
+    $article = $this->getTableLocator()->newEntity([
         'id' => 1,
         'title' => 'New Article',
         'created' => new DateTime('now')

en/orm/query-builder.rst

@@ -21,9 +21,9 @@ modified. You can also use a table's connection object to access the lower level
 Query builder that does not include ORM features, if necessary. See the
 :ref:`database-queries` section for more information::
 
-    use Cake\ORM\TableRegistry;
+    use Cake\ORM\Locator\LocatorAwareTrait;
 
-    $articles = TableRegistry::getTableLocator()->get('Articles');
+    $articles = $this->getTableLocator()->get('Articles');
 
     // Start a new query.
     $query = $articles->find();
@@ -40,9 +40,9 @@ Selecting Rows From A Table
 
 ::
 
-    use Cake\ORM\TableRegistry;
+    use Cake\ORM\Locator\LocatorAwareTrait;
 
-    $query = TableRegistry::getTableLocator()->get('Articles')->find();
+    $query = $this->getTableLocator()->get('Articles')->find();
 
     foreach ($query as $article) {
         debug($article->title);