Merge pull request #16433 from cakephp/4.4-paginator-classname

Rename "paginator" option to "className" for consistency.

src/Controller/Component/PaginatorComponent.php

@@ -19,7 +19,7 @@ namespace Cake\Controller\Component;
 use Cake\Controller\Component;
 use Cake\Controller\ComponentRegistry;
 use Cake\Datasource\Paging\Exception\PageOutOfBoundsException;
-use Cake\Datasource\Paging\Paginator;
+use Cake\Datasource\Paging\NumericPaginator;
 use Cake\Datasource\ResultSetInterface;
 use Cake\Http\Exception\NotFoundException;
 use InvalidArgumentException;
@@ -34,7 +34,7 @@ use UnexpectedValueException;
  * You configure pagination when calling paginate(). See that method for more details.
  *
  * @link https://book.cakephp.org/4/en/controllers/components/pagination.html
- * @mixin \Cake\Datasource\Paging\Paginator
+ * @mixin \Cake\Datasource\Paging\NumericPaginator
  * @deprecated 4.4.0 Use Cake\Datasource\Paging\Paginator directly.
  */
 class PaginatorComponent extends Component
@@ -42,7 +42,7 @@ class PaginatorComponent extends Component
     /**
      * Datasource paginator instance.
      *
-     * @var \Cake\Datasource\Paging\Paginator
+     * @var \Cake\Datasource\Paging\NumericPaginator
      */
     protected $_paginator;
 
@@ -52,7 +52,7 @@ class PaginatorComponent extends Component
     public function __construct(ComponentRegistry $registry, array $config = [])
     {
         deprecationWarning(
-            'PaginatorComponent is deprecated, use a Cake\Datasource\Pagination\Paginator instance directly.'
+            'PaginatorComponent is deprecated, use a Cake\Datasource\Pagination\NumericPaginator instance directly.'
         );
 
         if (!empty($this->_defaultConfig)) {
@@ -60,13 +60,13 @@ class PaginatorComponent extends Component
         }
 
         if (isset($config['paginator'])) {
-            if (!$config['paginator'] instanceof Paginator) {
-                throw new InvalidArgumentException('Paginator must be an instance of ' . Paginator::class);
+            if (!$config['paginator'] instanceof NumericPaginator) {
+                throw new InvalidArgumentException('Paginator must be an instance of ' . NumericPaginator::class);
             }
             $this->_paginator = $config['paginator'];
             unset($config['paginator']);
         } else {
-            $this->_paginator = new Paginator();
+            $this->_paginator = new NumericPaginator();
         }
 
         parent::__construct($registry, $config);
@@ -230,10 +230,10 @@ class PaginatorComponent extends Component
     /**
      * Set paginator instance.
      *
-     * @param \Cake\Datasource\Paging\Paginator $paginator Paginator instance.
+     * @param \Cake\Datasource\Paging\NumericPaginator $paginator Paginator instance.
      * @return $this
      */
-    public function setPaginator(Paginator $paginator)
+    public function setPaginator(NumericPaginator $paginator)
     {
         $this->_paginator = $paginator;
 
@@ -243,9 +243,9 @@ class PaginatorComponent extends Component
     /**
      * Get paginator instance.
      *
-     * @return \Cake\Datasource\Paging\Paginator
+     * @return \Cake\Datasource\Paging\NumericPaginator
      */
-    public function getPaginator(): Paginator
+    public function getPaginator(): NumericPaginator
     {
         return $this->_paginator;
     }

src/Controller/Controller.php

@@ -20,7 +20,7 @@ use Cake\Controller\Exception\MissingActionException;
 use Cake\Core\App;
 use Cake\Datasource\ModelAwareTrait;
 use Cake\Datasource\Paging\Exception\PageOutOfBoundsException;
-use Cake\Datasource\Paging\Paginator;
+use Cake\Datasource\Paging\NumericPaginator;
 use Cake\Datasource\Paging\PaginatorInterface;
 use Cake\Event\EventDispatcherInterface;
 use Cake\Event\EventDispatcherTrait;
@@ -135,7 +135,7 @@ class Controller implements EventListenerInterface, EventDispatcherInterface
      * tables your controller will be paginating.
      *
      * @var array
-     * @see \Cake\Controller\Component\PaginatorComponent
+     * @see \Cake\Datasource\Paging\NumericPaginator
      */
     public $paginate = [];
 
@@ -886,7 +886,7 @@ class Controller implements EventListenerInterface, EventDispatcherInterface
     /**
      * Handles pagination of records in Table objects.
      *
-     * Will load the referenced Table object, and have the PaginatorComponent
+     * Will load the referenced Table object, and have the paginator
      * paginate the query using the request date and settings defined in `$this->paginate`.
      *
      * This method will also make the PaginatorHelper available in the view.
@@ -925,10 +925,22 @@ class Controller implements EventListenerInterface, EventDispatcherInterface
             return $this->Paginator->paginate($table, $settings);
         }
 
-        $paginator = $settings['paginator'] ?? Paginator::class;
-        unset($settings['paginator']);
+        if (isset($settings['paginator'])) {
+            $settings['className'] = $settings['paginator'];
+            deprecationWarning(
+                '`paginator` option is deprecated,'
+                . ' use `className` instead a specify a paginator name/FQCN.'
+            );
+        }
+
+        $paginator = $settings['className'] ?? NumericPaginator::class;
+        unset($settings['className']);
         if (is_string($paginator)) {
-            $paginator = new $paginator();
+            $className = App::className($paginator, 'Datasource/Paging', 'Paginator');
+            if ($className === null) {
+                throw new InvalidArgumentException('Invalid paginator: ' . $paginator);
+            }
+            $paginator = new $className();
         }
         if (!$paginator instanceof PaginatorInterface) {
             throw new InvalidArgumentException('Paginator must be an instance of ' . PaginatorInterface::class);

src/Datasource/Paginator.php

@@ -2,9 +2,9 @@
 declare(strict_types=1);
 
 class_alias(
-    'Cake\Datasource\Paging\Paginator',
+    'Cake\Datasource\Paging\NumericPaginator',
     'Cake\Datasource\Paginator'
 );
 deprecationWarning(
-    'Use Cake\Datasource\Paging\Paginator instead of Cake\Datasource\Paginator.'
+    'Use Cake\Datasource\Paging\NumericPaginator instead of Cake\Datasource\Paginator.'
 );

src/Datasource/Paging/Paginator.php

@@ -26,7 +26,7 @@ use Cake\Datasource\ResultSetInterface;
 /**
  * This class is used to handle automatic model data pagination.
  */
-class Paginator implements PaginatorInterface
+class NumericPaginator implements PaginatorInterface
 {
     use InstanceConfigTrait;
 

src/Datasource/Paging/SimplePaginator.php

@@ -26,7 +26,7 @@ use Cake\Datasource\QueryInterface;
  * Instead use only the prev/next pagination controls, and handle 404 errors
  * when pagination goes past the available result set.
  */
-class SimplePaginator extends Paginator
+class SimplePaginator extends NumericPaginator
 {
     /**
      * Simple pagination does not perform any count query, so this method returns `null`.

tests/TestCase/Controller/Component/PaginatorComponentTest.php

@@ -121,7 +121,7 @@ class PaginatorComponentTest extends TestCase
     public function testInvalidPaginatorOption(): void
     {
         $this->expectException(InvalidArgumentException::class);
-        $this->expectExceptionMessage('Paginator must be an instance of Cake\Datasource\Paging\Paginator');
+        $this->expectExceptionMessage('Paginator must be an instance of Cake\Datasource\Paging\NumericPaginator');
         $this->deprecated(function () {
             new PaginatorComponent($this->registry, [
                 'paginator' => new stdClass(),

tests/TestCase/Controller/ControllerTest.php

@@ -672,6 +672,7 @@ class ControllerTest extends TestCase
         $this->assertFalse($paging['Posts']['nextPage']);
         $this->assertNull($paging['Posts']['scope']);
 
+        $Controller->paginate = ['className' => 'Numeric'];
         $results = $Controller->paginate($this->getTableLocator()->get('Posts'), ['scope' => 'posts']);
         $this->assertInstanceOf('Cake\Datasource\ResultSetInterface', $results);
         $this->assertCount(1, $results);
@@ -682,6 +683,15 @@ class ControllerTest extends TestCase
         $this->assertTrue($paging['Posts']['prevPage']);
         $this->assertFalse($paging['Posts']['nextPage']);
         $this->assertSame($paging['Posts']['scope'], 'posts');
+
+        $results = $Controller->paginate(
+            $this->getTableLocator()->get('Posts'),
+            ['className' => 'Simple']
+        );
+        $this->assertInstanceOf('Cake\Datasource\ResultSetInterface', $results);
+
+        $paging = $Controller->getRequest()->getAttribute('paging');
+        $this->assertSame($paging['Posts']['pageCount'], 0, 'SimplePaginator doesn\'t have a page count');
     }
 
     /**

tests/TestCase/Datasource/Paging/PaginatorTest.php

@@ -19,7 +19,7 @@ namespace Cake\Test\TestCase\Datasource\Paging;
 use Cake\ORM\Entity;
 use Cake\TestSuite\TestCase;
 
-class PaginatorTest extends TestCase
+class NumericPaginatorTest extends TestCase
 {
     use PaginatorTestTrait;
 

tests/TestCase/Datasource/Paging/PaginatorTestTrait.php

@@ -20,7 +20,7 @@ use Cake\Core\Configure;
 use Cake\Datasource\ConnectionManager;
 use Cake\Datasource\EntityInterface;
 use Cake\Datasource\Paging\Exception\PageOutOfBoundsException;
-use Cake\Datasource\Paging\Paginator;
+use Cake\Datasource\Paging\NumericPaginator;
 use Cake\Datasource\RepositoryInterface;
 
 trait PaginatorTestTrait
@@ -44,7 +44,7 @@ trait PaginatorTestTrait
 
         Configure::write('App.namespace', 'TestApp');
 
-        $this->Paginator = new Paginator();
+        $this->Paginator = new NumericPaginator();
 
         $this->Post = $this->getMockRepository();
     }

tests/TestCase/Datasource/Paging/SimplePaginatorTest.php

@@ -20,7 +20,7 @@ use Cake\Core\Configure;
 use Cake\Datasource\Paging\SimplePaginator;
 use Cake\ORM\Entity;
 
-class SimplePaginatorTest extends PaginatorTest
+class SimplePaginatorTest extends NumericPaginatorTest
 {
     public function setUp(): void
     {

tests/test_app/TestApp/Datasource/Paging/CustomPaginator.php

@@ -3,8 +3,8 @@ declare(strict_types=1);
 
 namespace TestApp\Datasource\Paging;
 
-use Cake\Datasource\Paging\Paginator;
+use Cake\Datasource\Paging\NumericPaginator;
 
-class CustomPaginator extends Paginator
+class CustomPaginator extends NumericPaginator
 {
 }