---
title: "Phalcon Paginator"
version: "5.20"
---
> Documentation Index
> Fetch the complete documentation index at: https://docs.phalcon.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Phalcon Paginator
:::info[NOTE]
All classes are prefixed with `Phalcon`
:::
## Paginator\Adapter\AbstractAdapter
Abstract
Phalcon\Paginator\Adapter\AbstractAdapter
- **`Phalcon\Paginator\Adapter\AbstractAdapter`** - implements [`Phalcon\Paginator\Adapter\AdapterInterface`](#paginatoradapteradapterinterface)
- [`Phalcon\Paginator\Adapter\Model`](#paginatoradaptermodel)
- [`Phalcon\Paginator\Adapter\NativeArray`](#paginatoradapternativearray)
- [`Phalcon\Paginator\Adapter\QueryBuilder`](#paginatoradapterquerybuilder)
- [`Phalcon\Paginator\Adapter\QueryBuilderCursor`](#paginatoradapterquerybuildercursor)
`Phalcon\Contracts\Paginator\PaginatorTypes` · `Phalcon\Paginator\Exception` · `Phalcon\Paginator\Exceptions\InvalidLimit` · `Phalcon\Paginator\Exceptions\MissingRequiredParameter` · `Phalcon\Paginator\Repository` · `Phalcon\Paginator\RepositoryInterface`
### Method Summary
Constructor
Get current rows limit
Set the current page number
Set current rows limit
Sets current repository for pagination
Gets current repository for pagination
### Properties
Configuration of paginator
Number of rows to show in the paginator. By default is null
Current page in paginate
Repository for pagination
### Methods
__construct()
```php
public function __construct( array $config );
```
Constructor
getLimit()
```php
public function getLimit(): int;
```
Get current rows limit
setCurrentPage()
```php
public function setCurrentPage( int $page ): AdapterInterface;
```
Set the current page number
setLimit()
```php
public function setLimit( int $limit ): AdapterInterface;
```
Set current rows limit
setRepository()
```php
public function setRepository( RepositoryInterface $repository ): AdapterInterface;
```
Sets current repository for pagination
getRepository()
```php
protected function getRepository( array|null $properties = null ): RepositoryInterface;
```
Gets current repository for pagination
## Paginator\Adapter\AdapterInterface
Interface
- [`Phalcon\Contracts\Paginator\Adapter`](/5.20/api/phalcon_contracts/#contractspaginatoradapter)
- **`Phalcon\Paginator\Adapter\AdapterInterface`**
`Phalcon\Contracts\Paginator\Adapter`
## Paginator\Adapter\Model
Class
This adapter allows to paginate data using a Phalcon\Mvc\Model resultset as a
base.
```php
use Phalcon\Paginator\Adapter\Model;
$paginator = new Model(
[
"model" => Invoices::class,
"limit" => 25,
"page" => $currentPage,
]
);
$paginator = new Model(
[
"model" => Invoices::class,
"parameters" => [
"columns" => "inv_id, inv_title"
],
"limit" => 12,
"page" => $currentPage,
]
);
$paginator = new Model(
[
"model" => Invoices::class,
"parameters" => [
"inv_status_flag = :flag:",
"bind" => [
"flag" => 1
],
"order" => "inv_title"
],
"limit" => 16,
"page" => $currentPage,
]
);
$paginator = new Model(
[
"model" => Invoices::class,
"parameters" => "(inv_id % 2) = 0",
"limit" => 8,
"page" => $currentPage,
]
);
$paginator = new Model(
[
"model" => Invoices::class,
"parameters" => [ "(inv_id % 2) = 0" ],
"limit" => 8,
"page" => $currentPage,
]
);
$paginate = $paginator->paginate();
```
- [`Phalcon\Paginator\Adapter\AbstractAdapter`](#paginatoradapterabstractadapter)
- **`Phalcon\Paginator\Adapter\Model`**
`Phalcon\Contracts\Paginator\PaginatorTypes` · `Phalcon\Paginator\Exceptions\MissingRequiredParameter` · `Phalcon\Paginator\RepositoryInterface`
### Method Summary
Phalcon\Paginator\Adapter\Model constructor
Returns a slice of the resultset to show in the pagination
### Methods
__construct()
```php
public function __construct( array $config );
```
Phalcon\Paginator\Adapter\Model constructor
paginate()
```php
public function paginate(): RepositoryInterface;
```
Returns a slice of the resultset to show in the pagination
## Paginator\Adapter\NativeArray
Class
Pagination using a PHP array as source of data
```php
use Phalcon\Paginator\Adapter\NativeArray;
$paginator = new NativeArray(
[
"data" => [
["id" => 1, "name" => "Artichoke"],
["id" => 2, "name" => "Carrots"],
["id" => 3, "name" => "Beet"],
["id" => 4, "name" => "Lettuce"],
["id" => 5, "name" => ""],
],
"limit" => 2,
"page" => $currentPage,
]
);
```
- [`Phalcon\Paginator\Adapter\AbstractAdapter`](#paginatoradapterabstractadapter)
- **`Phalcon\Paginator\Adapter\NativeArray`**
`Phalcon\Paginator\Exception` · `Phalcon\Paginator\Exceptions\PaginatorDataNotArray` · `Phalcon\Paginator\RepositoryInterface`
### Method Summary
Returns a slice of the resultset to show in the pagination
### Methods
paginate()
```php
public function paginate(): RepositoryInterface;
```
Returns a slice of the resultset to show in the pagination
## Paginator\Adapter\QueryBuilder
Class
Pagination using a PHQL query builder as source of data
```php
use Phalcon\Paginator\Adapter\QueryBuilder;
$builder = $this->modelsManager->createBuilder()
->columns("inv_id, inv_title")
->from(Invoices::class)
->orderBy("inv_title");
$paginator = new QueryBuilder(
[
"builder" => $builder,
"limit" => 20,
"page" => 1,
]
);
```
- [`Phalcon\Paginator\Adapter\AbstractAdapter`](#paginatoradapterabstractadapter)
- **`Phalcon\Paginator\Adapter\QueryBuilder`**
`Phalcon\Contracts\Db\Adapter\Adapter` · `Phalcon\Contracts\Paginator\PaginatorTypes` · `Phalcon\Db\Enum` · `Phalcon\Mvc\Model\Query\Builder` · `Phalcon\Paginator\Exception` · `Phalcon\Paginator\Exceptions\BuilderModelNotDefined` · `Phalcon\Paginator\Exceptions\InvalidBuilderInstance` · `Phalcon\Paginator\Exceptions\MissingColumnsForHaving` · `Phalcon\Paginator\Exceptions\MissingRequiredParameter` · `Phalcon\Paginator\RepositoryInterface`
### Method Summary
Phalcon\Paginator\Adapter\QueryBuilder
Get the current page number
Get query builder object
Returns a slice of the resultset to show in the pagination
Set query builder object
### Properties
Paginator's data
Column list used only for COUNT rewriting when the builder carries a
HAVING or GROUP BY clause. It supplies the columns for the subquery
that counts the grouped/having result set and is ignored otherwise.
### Methods
__construct()
```php
public function __construct( array $config );
```
Phalcon\Paginator\Adapter\QueryBuilder
The `columns` option is not a projection for the paginated rows; it is
consumed solely by the total-count rewrite when the builder has a
HAVING or GROUP BY clause (it becomes the column list of the counting
subquery). It has no effect on plain queries.
getCurrentPage()
```php
public function getCurrentPage(): int;
```
Get the current page number
getQueryBuilder()
```php
public function getQueryBuilder(): Builder;
```
Get query builder object
paginate()
```php
public function paginate(): RepositoryInterface;
```
Returns a slice of the resultset to show in the pagination
setQueryBuilder()
```php
public function setQueryBuilder( Builder $builder ): static;
```
Set query builder object
## Paginator\Adapter\QueryBuilderCursor
Class
Cursor-based (keyset) pagination using a PHQL query builder as source of
data.
Unlike offset pagination, this adapter does not use an ever-growing OFFSET.
It appends a WHERE condition on a unique, indexed cursor column so that each
page is an O(1) index seek regardless of depth.
Limitations:
- No total count: `getTotalItems()` always returns 0.
- No random access: `getLast()` always returns 0. Pages must be traversed
in order by following the cursor value returned in `getNext()`.
- The cursor column must be unique and indexed (e.g. a primary key).
- Items are returned as an array of associative arrays (via
`Resultset::toArray()`), not as model objects.
- `cursorColumn` must match the PHQL-accessible column name exactly
(e.g. `"inv_id"`).
```php
use Phalcon\Paginator\Adapter\QueryBuilderCursor;
$builder = $this->modelsManager->createBuilder()
->columns("inv_id, inv_title")
->from(Invoices::class)
->orderBy("inv_id");
$paginator = new QueryBuilderCursor(
[
"builder" => $builder,
"limit" => 20,
"cursorColumn" => "inv_id",
"cursor" => null, // first page; pass $page->getNext() for subsequent pages
]
);
$page = $paginator->paginate();
// $page->getItems() - array of rows for this page
// $page->getNext() - cursor value to pass for the next page (0 means no more pages)
// $page->getCurrent() - cursor value used for this page (0 on first page)
```
- [`Phalcon\Paginator\Adapter\AbstractAdapter`](#paginatoradapterabstractadapter)
- **`Phalcon\Paginator\Adapter\QueryBuilderCursor`**
`Phalcon\Contracts\Paginator\PaginatorTypes` · `Phalcon\Mvc\Model\Query\Builder` · `Phalcon\Paginator\Exceptions\InvalidBuilderInstance` · `Phalcon\Paginator\Exceptions\InvalidCursorColumn` · `Phalcon\Paginator\Exceptions\MissingRequiredParameter` · `Phalcon\Paginator\RepositoryInterface`
### Method Summary
Phalcon\Paginator\Adapter\QueryBuilderCursor
Get the current page number
Get the cursor value for the current page (null on first page)
Get the cursor column name
Get query builder object
Returns a slice of the resultset to show in the pagination
Set the cursor value for the next paginate() call
Set query builder object
### Properties
Paginator's data
The cursor value for the current page (null = first page)
The column used as the cursor (must be unique and indexed)
### Methods
__construct()
```php
public function __construct( array $config );
```
Phalcon\Paginator\Adapter\QueryBuilderCursor
getCurrentPage()
```php
public function getCurrentPage(): int;
```
Get the current page number
Returns the cursor value used for this page cast to int, or 0 for the
first page. Use getCursor() to retrieve the raw cursor value.
getCursor()
```php
public function getCursor(): mixed;
```
Get the cursor value for the current page (null on first page)
getCursorColumn()
```php
public function getCursorColumn(): string;
```
Get the cursor column name
getQueryBuilder()
```php
public function getQueryBuilder(): Builder;
```
Get query builder object
paginate()
```php
public function paginate(): RepositoryInterface;
```
Returns a slice of the resultset to show in the pagination
Fetches `limit + 1` rows from the builder. If the extra row is present
a next page exists; it is discarded and the cursor value of the last
included row is stored in the `next` repository property.
setCursor()
```php
public function setCursor( mixed $cursor ): static;
```
Set the cursor value for the next paginate() call
Pass the value returned by Repository::getNext() to advance to the
next page, or null to restart from the first page.
setQueryBuilder()
```php
public function setQueryBuilder( Builder $builder ): static;
```
Set query builder object
## Paginator\Exception
Class
Exceptions thrown in Phalcon\Paginator will use this class
- `\Exception`
- **`Phalcon\Paginator\Exception`**
- [`Phalcon\Paginator\Exceptions\BuilderModelNotDefined`](#paginatorexceptionsbuildermodelnotdefined)
- [`Phalcon\Paginator\Exceptions\InvalidBuilderInstance`](#paginatorexceptionsinvalidbuilderinstance)
- [`Phalcon\Paginator\Exceptions\InvalidCursorColumn`](#paginatorexceptionsinvalidcursorcolumn)
- [`Phalcon\Paginator\Exceptions\InvalidLimit`](#paginatorexceptionsinvalidlimit)
- [`Phalcon\Paginator\Exceptions\MissingColumnsForHaving`](#paginatorexceptionsmissingcolumnsforhaving)
- [`Phalcon\Paginator\Exceptions\MissingRequiredParameter`](#paginatorexceptionsmissingrequiredparameter)
- [`Phalcon\Paginator\Exceptions\PaginatorDataNotArray`](#paginatorexceptionspaginatordatanotarray)
## Paginator\Exceptions\BuilderModelNotDefined
Class
- `\Exception`
- [`Phalcon\Paginator\Exception`](#paginatorexception)
- **`Phalcon\Paginator\Exceptions\BuilderModelNotDefined`**
`Phalcon\Paginator\Exception`
### Method Summary
### Methods
__construct()
```php
public function __construct();
```
## Paginator\Exceptions\InvalidBuilderInstance
Class
- `\Exception`
- [`Phalcon\Paginator\Exception`](#paginatorexception)
- **`Phalcon\Paginator\Exceptions\InvalidBuilderInstance`**
`Phalcon\Paginator\Exception`
### Method Summary
### Methods
__construct()
```php
public function __construct();
```
## Paginator\Exceptions\InvalidCursorColumn
Class
- `\Exception`
- [`Phalcon\Paginator\Exception`](#paginatorexception)
- **`Phalcon\Paginator\Exceptions\InvalidCursorColumn`**
`Phalcon\Paginator\Exception`
### Method Summary
### Methods
__construct()
```php
public function __construct();
```
## Paginator\Exceptions\InvalidLimit
Class
- `\Exception`
- [`Phalcon\Paginator\Exception`](#paginatorexception)
- **`Phalcon\Paginator\Exceptions\InvalidLimit`**
`Phalcon\Paginator\Exception`
### Method Summary
### Methods
__construct()
```php
public function __construct();
```
## Paginator\Exceptions\MissingColumnsForHaving
Class
- `\Exception`
- [`Phalcon\Paginator\Exception`](#paginatorexception)
- **`Phalcon\Paginator\Exceptions\MissingColumnsForHaving`**
`Phalcon\Paginator\Exception`
### Method Summary
### Methods
__construct()
```php
public function __construct();
```
## Paginator\Exceptions\MissingRequiredParameter
Class
- `\Exception`
- [`Phalcon\Paginator\Exception`](#paginatorexception)
- **`Phalcon\Paginator\Exceptions\MissingRequiredParameter`**
`Phalcon\Paginator\Exception`
### Method Summary
### Methods
__construct()
```php
public function __construct( string $parameter );
```
getParameter()
```php
public function getParameter(): string;
```
## Paginator\Exceptions\PaginatorDataNotArray
Class
- `\Exception`
- [`Phalcon\Paginator\Exception`](#paginatorexception)
- **`Phalcon\Paginator\Exceptions\PaginatorDataNotArray`**
`Phalcon\Paginator\Exception`
### Method Summary
### Methods
__construct()
```php
public function __construct();
```
## Paginator\PaginatorFactory
Class
- [`Phalcon\Factory\AbstractConfigFactory`](/5.20/api/phalcon_factory/#factoryabstractconfigfactory)
- [`Phalcon\Factory\AbstractFactory`](/5.20/api/phalcon_factory/#factoryabstractfactory)
- **`Phalcon\Paginator\PaginatorFactory`**
`Phalcon\Config\Config` · `Phalcon\Config\ConfigInterface` · `Phalcon\Contracts\Paginator\PaginatorTypes` · `Phalcon\Factory\AbstractFactory` · `Phalcon\Paginator\Adapter\AdapterInterface` · `Phalcon\Paginator\Adapter\Model` · `Phalcon\Paginator\Adapter\NativeArray` · `Phalcon\Paginator\Adapter\QueryBuilder` · `Phalcon\Paginator\Adapter\QueryBuilderCursor` · `Throwable`
### Method Summary
AdapterFactory constructor.
Factory to create an instance from a Config object
Create a new instance of the adapter
Returns the available adapters
### Methods
__construct()
```php
public function __construct( array $services = [] );
```
AdapterFactory constructor.
load()
```php
public function load( mixed $config ): AdapterInterface;
```
Factory to create an instance from a Config object
```php
use Phalcon\Paginator\PaginatorFactory;
$builder = $this
->modelsManager
->createBuilder()
->columns("inv_id, inv_title")
->from(Invoices::class)
->orderBy("inv_title");
$options = [
"builder" => $builder,
"limit" => 20,
"page" => 1,
"adapter" => "queryBuilder",
];
$paginator = (new PaginatorFactory())->load($options);
```
newInstance()
```php
public function newInstance(
string $name,
array $options = []
): AdapterInterface;
```
Create a new instance of the adapter
getExceptionClass()
```php
protected function getExceptionClass(): string;
```
getServices()
```php
protected function getServices(): array;
```
Returns the available adapters
## Paginator\Repository
Class
Repository of current state Phalcon\Paginator\AdapterInterface::paginate()
- **`Phalcon\Paginator\Repository`** - implements [`Phalcon\Paginator\RepositoryInterface`](#paginatorrepositoryinterface), `\JsonSerializable`
`JsonSerializable` · `Phalcon\Contracts\Paginator\PaginatorTypes`
### Method Summary
Gets value of property by name
Resolve alias property name
### Properties
### Methods
__get()
```php
public function __get( string $property ): mixed|null;
```
getAliases()
```php
public function getAliases(): array;
```
getCurrent()
```php
public function getCurrent(): int;
```
getFirst()
```php
public function getFirst(): int;
```
getItems()
```php
public function getItems(): mixed;
```
getLast()
```php
public function getLast(): int;
```
getLimit()
```php
public function getLimit(): int;
```
getNext()
```php
public function getNext(): int;
```
getPrevious()
```php
public function getPrevious(): int;
```
getTotalItems()
```php
public function getTotalItems(): int;
```
jsonSerialize()
```php
public function jsonSerialize(): array;
```
setAliases()
```php
public function setAliases( array $aliases ): RepositoryInterface;
```
setProperties()
```php
public function setProperties( array $properties ): RepositoryInterface;
```
getProperty()
```php
protected function getProperty(
string $property,
mixed $defaultValue = null
): mixed;
```
Gets value of property by name
The repository is filled by the adapters, which store an int under every
property that has an int default, so callers passing one are handed an
int back.
getRealNameProperty()
```php
protected function getRealNameProperty( string $property ): string;
```
Resolve alias property name
## Paginator\RepositoryInterface
Interface
- [`Phalcon\Contracts\Paginator\Repository`](/5.20/api/phalcon_contracts/#contractspaginatorrepository)
- **`Phalcon\Paginator\RepositoryInterface`**
`Phalcon\Contracts\Paginator\Repository`
Source: https://docs.phalcon.io/5.20/api/phalcon_paginator/index.mdx