---
title: "Phalcon Paginator"
version: "5.19"
---
> 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\Contracts\Paginator\PaginatorTypes` · `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 );
```
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|null $properties = null ): RepositoryInterface;
```
Gets current repository for pagination
## Paginator\Adapter\AdapterInterface
Interface
Source on GitHub
- [`Phalcon\Contracts\Paginator\Adapter`](/5.19/api/phalcon_contracts/#contractspaginatoradapter)
- **`Phalcon\Paginator\Adapter\AdapterInterface`**
__Uses__ `Phalcon\Contracts\Paginator\Adapter`
## Paginator\Adapter\Model
Class
Source on GitHub
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\Contracts\Paginator\PaginatorTypes` · `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
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
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\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
### Properties
protected
Builder
$builder
Paginator's data
protected
paginator_columns|null
$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
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\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
### 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
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.19/api/phalcon_factory/#factoryabstractconfigfactory)
- [`Phalcon\Factory\AbstractFactory`](/5.19/api/phalcon_factory/#factoryabstractfactory)
- **`Phalcon\Paginator\PaginatorFactory`**
__Uses__ `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
### 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
Repository of current state Phalcon\Paginator\AdapterInterface::paginate()
- **`Phalcon\Paginator\Repository`** - implements [`Phalcon\Paginator\RepositoryInterface`](#paginatorrepositoryinterface), `\JsonSerializable`
__Uses__ `JsonSerializable` · `Phalcon\Contracts\Paginator\PaginatorTypes`
### Method Summary
### Properties
protected
paginator_aliases
$aliases = []
protected
paginator_properties
$properties = []
### Methods
Public · 13
__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;
```
Protected · 2
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
Source on GitHub
- [`Phalcon\Contracts\Paginator\Repository`](/5.19/api/phalcon_contracts/#contractspaginatorrepository)
- **`Phalcon\Paginator\RepositoryInterface`**
__Uses__ `Phalcon\Contracts\Paginator\Repository`
Source: https://docs.phalcon.io/5.19/api/phalcon_paginator/index.mdx