Paginator
*********

.[perex]
Need to page a data listing? Because mathematics behind pagination can be tricky, [api:Nette\Utils\Paginator] will help you.


Installation:

```shell
composer require nette/utils
```

Lets create a paging object and set basic information for it:

```php
$paginator = new Nette\Utils\Paginator;
$paginator->setPage(1); // the number of the current page (numbered from 1)
$paginator->setItemsPerPage(30); // the number of records per page
$paginator->setItemCount(356); // the total number of records (if available)
```

Pages are numbered from 1. We can change it using `setBase()`:

```php
$paginator->setBase(0); // numbered from 0
```

The object will now provide all the basic information useful in creating a paginator. You can, for example, pass it to a template and use it there.

```php
$paginator->isFirst(); // is this the first page?
$paginator->isLast(); // is this the last page?
$paginator->getPage(); // current page number
$paginator->getFirstPage(); // the first page number
$paginator->getLastPage(); // the last page number
$paginator->getFirstItemOnPage(); // sequence number of the first item on the page
$paginator->getLastItemOnPage(); // sequence number of the last item on the page
$paginator->getPageIndex(); // current page number if numbered from 0
$paginator->getPageCount(); // the total number of pages
$paginator->getItemsPerPage(); // the number of records per page
$paginator->getItemCount(); // the total number of records (if available)
```

The paginator will help in formulating the SQL query. The `getLength()` and `getOffset()` methods return the values you may use in the LIMIT and OFFSET clauses:

```php
$result = $database->query(
	'SELECT * FROM items LIMIT ? OFFSET ?',
	$paginator->getLength(),
	$paginator->getOffset(),
);
```

If you need to paginate in reverse order, i.e. page no. 1 corresponds to the highest offset, you may use `getCountdownOffset()`:

```php
$result = $database->query(
	'SELECT * FROM items LIMIT ? OFFSET ?',
	$paginator->getLength(),
	$paginator->getCountdownOffset(),
);
```

An example of use in the application can be found in the cookbook [Paginating Database Results |best-practices:pagination].