Pagination

The process of pagination takes place when we need to present big groups of arbitrary data gradually. 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:

You can use the Pagination Factory class to instantiate a new paginator object:

<?php
use Phalcon\Paginator\PaginatorFactory;
$builder = $this
    ->modelsManager
    ->createBuilder()
    ->columns('id, lastName, firstName')
    ->from(Users::class)
    ->orderBy('name')
;
$options = [
    'builder' => $builder,
    'limit'   => 20,
    'page'    => 1,
    'adapter' => 'queryBuilder',
];
$paginator = (new PaginatorFactory())->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:

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

<table>
    <tr>
        <th>Id</th>
        <th>Active</th>
        <th>Last Name</th>
        <th>First Name</th>
    </tr>
    <tr>
        <td><?php echo $item->id; ?></td>
        <td><?php echo ($item->active) ? 'Y' : 'N'; ?></td>
        <td><?php echo $item->lastName; ?></td>
        <td><?php echo $item->firstName; ?></td>
    </tr>
</table>

The $page object also contains navigation data:

<?php
use Phalcon\Paginator\AdapterFactory;
$factory = new AdapterFactory();
// Passing a resultset as data
$options = [
   'data'  => Products::find(),
   'limit' => 10,
   'page'  => $currentPage,
];
$paginator = $factory->newInstance('model', $options);
// Passing an array as data
$options = [
    'data'  => [
        ['id' => 1, 'name' => 'Artichoke'],
        ['id' => 2, 'name' => 'Carrots'],
        ['id' => 3, 'name' => 'Beet'],
        ['id' => 4, 'name' => 'Lettuce'],
        ['id' => 5, 'name' => ''],
    ],
    'limit' => 2,
    'page'  => $currentPage,
];
$paginator = $factory->newInstance('nativeArray', $options);
// Passing a QueryBuilder as data
    ->modelsManager
    ->createBuilder()
    ->columns('id, name')
    ->from('Robots')
$options = [
    'builder' => $builder,
    'limit'   => 20,
    'page'    => 1,
];
$paginator = $factory->newInstance('queryBuilder', $options);

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

Page Attributes

The $page object has the following attributes:

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

<?php
use Phalcon\Paginator\AdapterInterface as PaginatorInterface;
use Phalcon\Paginator\RepositoryInterface;
class MyPaginator implements PaginatorInterface
{
    /**
     * Get current rows limit
     */
    public function getLimit(): int;
    /**
     * Returns a slice of the resultset to show in the pagination
     */
    public function paginate(): RepositoryInterface;
    /**
     * Set the current page number
     */
    public function setCurrentPage(int $page);
    /**
     * Set current rows limit
     */
}