Pagination

The process of pagination takes place when we need to present big groups of arbitrary data gradually. Phalcon\Paginator offers a fast and convenient way to split these sets of data into browsable pages.

Data Adapters

This component makes use of adapters to encapsulate different sources of data:

AdapterDescription
Phalcon\Paginator\Adapter\NativeArrayUse a PHP array as source data
Phalcon\Paginator\Adapter\ModelUse a Phalcon\Mvc\Model\Resultset object as source data. Since PDO doesn’t support scrollable cursors this adapter shouldn’t be used to paginate a large number of records
Phalcon\Paginator\Adapter\QueryBuilderUse a Phalcon\Mvc\Model\Query\Builder object as source data

Factory

Loads Paginator Adapter class using adapter option

  1. <?php
  3. use Phalcon\Paginator\Factory;
  5. $builder = $this->modelsManager->createBuilder()
  6.                 ->columns('id, name')
  7.                 ->from('Robots')
  8.                 ->orderBy('name');
  10. $options = [
  11.     'builder' => $builder,
  12.     'limit'   => 20,
  13.     'page'    => 1,
  14.     'adapter' => 'queryBuilder',
  15. ];
  17. $paginator = Factory::load($options);

Examples

In the example below, the paginator will use the result of a query from a model as its source data, and limit the displayed data to 10 records per page:

  1. <?php
  3. use Phalcon\Paginator\Adapter\Model as PaginatorModel;
  5. // Current page to show
  6. // In a controller/component this can be:
  7. // $this->request->getQuery('page', 'int'); // GET
  8. // $this->request->getPost('page', 'int'); // POST
  9. $currentPage = (int) $_GET['page'];
  11. // The data set to paginate
  12. $robots = Robots::find();
  14. // Create a Model paginator, show 10 rows by page starting from $currentPage
  15. $paginator = new PaginatorModel(
  16.     [
  17.         'data'  => $robots,
  18.         'limit' => 10,
  19.         'page'  => $currentPage,
  20.     ]
  21. );
  23. // Get the paginated results
  24. $page = $paginator->getPaginate();

The $currentPage variable controls the page to be displayed. The $paginator->getPaginate() returns a $page object that contains the paginated data. It can be used for generating the pagination:

  1. <table>
  2.     <tr>
  3.         <th>Id</th>
  4.         <th>Name</th>
  5.         <th>Type</th>
  6.     </tr>
  7.     <?php foreach ($page->items as $item) { ?>
  8.     <tr>
  9.         <td><?php echo $item->id; ?></td>
  10.         <td><?php echo $item->name; ?></td>
  11.         <td><?php echo $item->type; ?></td>
  12.     </tr>
  13.     <?php } ?>
  14. </table>

The $page object also contains navigation data:

  1. <a href='/robots/search'>First</a>
  2. <a href='/robots/search?page=<?= $page->before; ?>'>Previous</a>
  3. <a href='/robots/search?page=<?= $page->next; ?>'>Next</a>
  4. <a href='/robots/search?page=<?= $page->last; ?>'>Last</a>
  6. <?php echo 'You are in page ', $page->current, ' of ', $page->total_pages; ?>

Using Adapters

An example of the source data that must be used for each adapter:

  1. <?php
  3. use Phalcon\Paginator\Adapter\Model as PaginatorModel;
  4. use Phalcon\Paginator\Adapter\NativeArray as PaginatorArray;
  5. use Phalcon\Paginator\Adapter\QueryBuilder as PaginatorQueryBuilder;
  7. // Passing a resultset as data
  8. $paginator = new PaginatorModel(
  9.     [
  10.         'data'  => Products::find(),
  11.         'limit' => 10,
  12.         'page'  => $currentPage,
  13.     ]
  14. );
  16. // Passing an array as data
  17. $paginator = new PaginatorArray(
  18.     [
  19.         'data'  => [
  20.             ['id' => 1, 'name' => 'Artichoke'],
  21.             ['id' => 2, 'name' => 'Carrots'],
  22.             ['id' => 3, 'name' => 'Beet'],
  23.             ['id' => 4, 'name' => 'Lettuce'],
  24.             ['id' => 5, 'name' => ''],
  25.         ],
  26.         'limit' => 2,
  27.         'page'  => $currentPage,
  28.     ]
  29. );
  31. // Passing a QueryBuilder as data
  33. $builder = $this->modelsManager->createBuilder()
  34.     ->columns('id, name')
  35.     ->from('Robots')
  36.     ->orderBy('name');
  38. $paginator = new PaginatorQueryBuilder(
  39.     [
  40.         'builder' => $builder,
  41.         'limit'   => 20,
  42.         'page'    => 1,
  43.     ]
  44. );

Page Attributes

The $page object has the following attributes:

AttributeDescription
itemsThe set of records to be displayed at the current page
currentThe current page
beforeThe previous page to the current one
nextThe next page to the current one
lastThe last page in the set of records
total_pagesThe number of pages
total_itemsThe number of items in the source data

Implementing your own adapters

The Phalcon\Paginator\AdapterInterface interface must be implemented in order to create your own paginator adapters or extend the existing ones:

  1. <?php
  3. use Phalcon\Paginator\AdapterInterface as PaginatorInterface;
  5. class MyPaginator implements PaginatorInterface
  6. {
  7.     /**
  8.      * Adapter constructor
  9.      *
  10.      * @param array $config
  11.      */
  12.     public function __construct($config);
  14.     /**
  15.      * Set the current page number
  16.      *
  17.      * @param int $page
  18.      */
  19.     public function setCurrentPage($page);
  21.     /**
  22.      * Returns a slice of the resultset to show in the pagination
  23.      *
  24.      * @return stdClass
  25.      */
  26.     public function getPaginate();
  27. }