---
title: "Phalcon Paginator"
version: "5.17"
---
> 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
Source on GitHub
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)
__Uses__ `Phalcon\Paginator\Exception` · `Phalcon\Paginator\Exceptions\InvalidLimit` · `Phalcon\Paginator\Exceptions\MissingRequiredParameter` · `Phalcon\Paginator\Repository` · `Phalcon\Paginator\RepositoryInterface`
### Method Summary
### Properties
protected
array
$config
Configuration of paginator
protected
int|null
$limitRows = null
Number of rows to show in the paginator. By default is null
protected
int|null
$page = null
Current page in paginate
protected
RepositoryInterface
$repository
Repository for pagination
### Methods
Public · 5
__construct()
```php
public function __construct( array $config );
```
Phalcon\Paginator\Adapter\AbstractAdapter 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
Protected · 1
getRepository()
```php
protected function getRepository( array $properties = null ): RepositoryInterface;
```
Gets current repository for pagination
## Paginator\Adapter\AdapterInterface
Interface
Source on GitHub
- [`Phalcon\Contracts\Paginator\Adapter`](/5.17/api/phalcon_contracts/#contractspaginatoradapter)
- **`Phalcon\Paginator\Adapter\AdapterInterface`**
__Uses__ `Phalcon\Contracts\Paginator\Adapter`
## Paginator\Adapter\Model
Class
Source on GitHub
Phalcon\Paginator\Adapter\Model
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`**
__Uses__ `Phalcon\Mvc\ModelInterface` · `Phalcon\Mvc\Model\ResultsetInterface` · `Phalcon\Paginator\Exception` · `Phalcon\Paginator\Exceptions\MissingRequiredParameter` · `Phalcon\Paginator\RepositoryInterface`
### Method Summary
### Methods
Public · 2
__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
Source on GitHub
Phalcon\Paginator\Adapter\NativeArray
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`**
__Uses__ `Phalcon\Paginator\Exception` · `Phalcon\Paginator\Exceptions\PaginatorDataNotArray` · `Phalcon\Paginator\RepositoryInterface`
### Method Summary
### Methods
Public · 1
paginate()
```php
public function paginate(): RepositoryInterface;
```
Returns a slice of the resultset to show in the pagination
## Paginator\Adapter\QueryBuilder
Class
Source on GitHub
Phalcon\Paginator\Adapter\QueryBuilder
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`**
__Uses__ `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
### Properties
protected
Builder
$builder
Paginator's data
protected
array|string
$columns
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
Public · 5
__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
Source on GitHub
Phalcon\Paginator\Adapter\QueryBuilderCursor
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`**
__Uses__ `Phalcon\Mvc\Model\Query\Builder` · `Phalcon\Paginator\Exception` · `Phalcon\Paginator\Exceptions\InvalidBuilderInstance` · `Phalcon\Paginator\Exceptions\InvalidCursorColumn` · `Phalcon\Paginator\Exceptions\MissingRequiredParameter` · `Phalcon\Paginator\RepositoryInterface`
### Method Summary
### Properties
protected
Builder
$builder
Paginator's data
protected
mixed
$cursor = null
The cursor value for the current page (null = first page)
protected
string
$cursorColumn
The column used as the cursor (must be unique and indexed)
### Methods
Public · 8
__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
Source on GitHub
Phalcon\Paginator\Exception
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
Source on GitHub
- `\Exception`
- [`Phalcon\Paginator\Exception`](#paginatorexception)
- **`Phalcon\Paginator\Exceptions\BuilderModelNotDefined`**
__Uses__ `Phalcon\Paginator\Exception`
### Method Summary
### Methods
Public · 1
__construct()
```php
public function __construct();
```
## Paginator\Exceptions\InvalidBuilderInstance
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Paginator\Exception`](#paginatorexception)
- **`Phalcon\Paginator\Exceptions\InvalidBuilderInstance`**
__Uses__ `Phalcon\Paginator\Exception`
### Method Summary
### Methods
Public · 1
__construct()
```php
public function __construct();
```
## Paginator\Exceptions\InvalidCursorColumn
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Paginator\Exception`](#paginatorexception)
- **`Phalcon\Paginator\Exceptions\InvalidCursorColumn`**
__Uses__ `Phalcon\Paginator\Exception`
### Method Summary
### Methods
Public · 1
__construct()
```php
public function __construct();
```
## Paginator\Exceptions\InvalidLimit
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Paginator\Exception`](#paginatorexception)
- **`Phalcon\Paginator\Exceptions\InvalidLimit`**
__Uses__ `Phalcon\Paginator\Exception`
### Method Summary
### Methods
Public · 1
__construct()
```php
public function __construct();
```
## Paginator\Exceptions\MissingColumnsForHaving
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Paginator\Exception`](#paginatorexception)
- **`Phalcon\Paginator\Exceptions\MissingColumnsForHaving`**
__Uses__ `Phalcon\Paginator\Exception`
### Method Summary
### Methods
Public · 1
__construct()
```php
public function __construct();
```
## Paginator\Exceptions\MissingRequiredParameter
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Paginator\Exception`](#paginatorexception)
- **`Phalcon\Paginator\Exceptions\MissingRequiredParameter`**
__Uses__ `Phalcon\Paginator\Exception`
### Method Summary
### Methods
Public · 2
__construct()
```php
public function __construct( string $parameter );
```
getParameter()
```php
public function getParameter(): string;
```
## Paginator\Exceptions\PaginatorDataNotArray
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Paginator\Exception`](#paginatorexception)
- **`Phalcon\Paginator\Exceptions\PaginatorDataNotArray`**
__Uses__ `Phalcon\Paginator\Exception`
### Method Summary
### Methods
Public · 1
__construct()
```php
public function __construct();
```
## Paginator\PaginatorFactory
Class
Source on GitHub
- [`Phalcon\Factory\AbstractConfigFactory`](/5.17/api/phalcon_factory/#factoryabstractconfigfactory)
- [`Phalcon\Factory\AbstractFactory`](/5.17/api/phalcon_factory/#factoryabstractfactory)
- **`Phalcon\Paginator\PaginatorFactory`**
__Uses__ `Phalcon\Factory\AbstractFactory` · `Phalcon\Paginator\Adapter\AdapterInterface`
### Method Summary
### Methods
Public · 3
__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
Protected · 2
getExceptionClass()
```php
protected function getExceptionClass(): string;
```
getServices()
```php
protected function getServices(): array;
```
Returns the available adapters
## Paginator\Repository
Class
Source on GitHub
Phalcon\Paginator\Repository
Repository of current state Phalcon\Paginator\AdapterInterface::paginate()
- **`Phalcon\Paginator\Repository`** - implements [`Phalcon\Paginator\RepositoryInterface`](#paginatorrepositoryinterface), `JsonSerializable`
__Uses__ `JsonSerializable`
### Method Summary
### Properties
protected
array
$aliases = []
protected
array
$properties = []
### Methods
Public · 13
__get()
```php
public function __get( string $property ): mixed|null;
```
\{@inheritdoc\}
getAliases()
```php
public function getAliases(): array;
```
\{@inheritdoc\}
getCurrent()
```php
public function getCurrent(): int;
```
\{@inheritdoc\}
getFirst()
```php
public function getFirst(): int;
```
\{@inheritdoc\}
getItems()
```php
public function getItems(): mixed;
```
\{@inheritdoc\}
getLast()
```php
public function getLast(): int;
```
\{@inheritdoc\}
getLimit()
```php
public function getLimit(): int;
```
\{@inheritdoc\}
getNext()
```php
public function getNext(): int;
```
\{@inheritdoc\}
getPrevious()
```php
public function getPrevious(): int;
```
\{@inheritdoc\}
getTotalItems()
```php
public function getTotalItems(): int;
```
\{@inheritdoc\}
jsonSerialize()
```php
public function jsonSerialize(): array;
```
See [jsonSerialize](https://php.net/manual/en/jsonserializable.jsonserialize.php)
setAliases()
```php
public function setAliases( array $aliases ): RepositoryInterface;
```
\{@inheritdoc\}
setProperties()
```php
public function setProperties( array $properties ): RepositoryInterface;
```
\{@inheritdoc\}
Protected · 2
getProperty()
```php
protected function getProperty(
string $property,
mixed $defaultValue = null
): mixed;
```
Gets value of property by name
getRealNameProperty()
```php
protected function getRealNameProperty( string $property ): string;
```
Resolve alias property name
## Paginator\RepositoryInterface
Interface
Source on GitHub
- [`Phalcon\Contracts\Paginator\Repository`](/5.17/api/phalcon_contracts/#contractspaginatorrepository)
- **`Phalcon\Paginator\RepositoryInterface`**
__Uses__ `Phalcon\Contracts\Paginator\Repository`
Source: https://docs.phalcon.io/5.17/api/phalcon_paginator/index.mdx