# Pagination

> Pagination represents information relevant to pagination of data items.

[API reference](/docs/api/index.md) › [yii](/docs/api/yii/index.md) › [data](/docs/api/yii/data/index.md) › Pagination

| class | `yii\data\Pagination` |
| --- | --- |
| Extends | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| Implements | [`yii\web\Linkable`](/docs/api/yii/web/linkable/index.md), [`yii\base\Configurable`](/docs/api/yii/base/configurable/index.md) |
| Since | 2.0 |
| Source | [`framework/data/Pagination.php`](https://github.com/yiisoft/yii2/blob/22.0/framework/data/Pagination.php#L78) |

Pagination represents information relevant to pagination of data items.

When data needs to be rendered in multiple pages, Pagination can be used to
represent information such as [total item count](/docs/api/yii/data/pagination/index.md#property-totalCount), [page size](/docs/api/yii/data/pagination/index.md#property-pageSize),
[current page](/docs/api/yii/data/pagination/index.md#property-page), etc. These information can be passed to [pagers](/docs/api/yii/widgets/linkpager/index.md)
to render pagination buttons or links.

The following example shows how to create a pagination object and feed it
to a pager.

Controller action:

```
public function actionIndex()
{
    $query = Article::find()->where(['status' => 1]);
    $countQuery = clone $query;
    $pages = new Pagination(['totalCount' => $countQuery->count()]);
    $models = $query->offset($pages->offset)
        ->limit($pages->limit)
        ->all();

    return $this->render('index', [
         'models' => $models,
         'pages' => $pages,
    ]);
}
```

View:

```
foreach ($models as $model) {
    // display $model here
}

// display pagination
echo LinkPager::widget([
    'pagination' => $pages,
]);
```

For more details and usage information on Pagination, see the [guide article on pagination](/docs/guide/output-pagination/index.md).

## Properties

| Property | Type | Description | Defined by |
| --- | --- | --- | --- |
| [`$defaultPageSize`](#property-defaultPageSize) | `int` | The default page size. Default: `20`. | `Pagination` |
| [`$forcePageParam`](#property-forcePageParam) | `bool` | Whether to always have the page parameter in the URL created by [`createUrl()`](/docs/api/yii/data/pagination/index.md#method-createUrl). Default: `true`. | `Pagination` |
| [`$limit`](#property-limit) read-only | `int` | The limit of the data. | `Pagination` |
| [`$links`](#property-links) read-only | `array` | The links for navigational purpose. | `Pagination` |
| [`$offset`](#property-offset) read-only | `int` | The offset of the data. | `Pagination` |
| <span id="property-page"></span>`$page` | `int` | The zero-based current page number. | `Pagination` |
| <span id="property-pageCount"></span>`$pageCount` read-only | `int` | Number of pages. | `Pagination` |
| <span id="property-pageParam"></span>`$pageParam` | `string` | Name of the parameter storing the current page index. Default: `'page'`. | `Pagination` |
| [`$pageSize`](#property-pageSize) | `int` | The number of items per page. | `Pagination` |
| [`$pageSizeLimit`](#property-pageSizeLimit) | `array\|false` | The page size limits. Default: `[1, 50]`. | `Pagination` |
| <span id="property-pageSizeParam"></span>`$pageSizeParam` | `string` | Name of the parameter storing the page size. Default: `'per-page'`. | `Pagination` |
| [`$params`](#property-params) | `array\|null` | Parameters (name => value) that should be used to obtain the current page number and to create new pagination URLs. Default: `null`. | `Pagination` |
| [`$route`](#property-route) | `string\|null` | The route of the controller action for displaying the paged contents. Default: `null`. | `Pagination` |
| <span id="property-totalCount"></span>`$totalCount` | `int` | Total number of items. Default: `0`. | `Pagination` |
| [`$urlManager`](#property-urlManager) | [`yii\web\UrlManager`](/docs/api/yii/web/urlmanager/index.md)`\|null` | The URL manager used for creating pagination URLs. Default: `null`. | `Pagination` |
| [`$validatePage`](#property-validatePage) | `bool` | Whether to check if [`$page`](/docs/api/yii/data/pagination/index.md#property-page) is within valid range. Default: `true`. | `Pagination` |

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| <span id="method-__construct"></span>[`__construct()`](/docs/api/yii/base/baseobject/index.md#method-__construct) | Constructor. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__call"></span>[`__call()`](/docs/api/yii/base/baseobject/index.md#method-__call) | Calls the named method which is not a class method. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__get"></span>[`__get()`](/docs/api/yii/base/baseobject/index.md#method-__get) | Returns the value of an object property. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__isset"></span>[`__isset()`](/docs/api/yii/base/baseobject/index.md#method-__isset) | Checks if a property is set, i.e. defined and not null. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__set"></span>[`__set()`](/docs/api/yii/base/baseobject/index.md#method-__set) | Sets value of an object property. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__unset"></span>[`__unset()`](/docs/api/yii/base/baseobject/index.md#method-__unset) | Sets an object property to null. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-canGetProperty"></span>[`canGetProperty()`](/docs/api/yii/base/baseobject/index.md#method-canGetProperty) | Returns a value indicating whether a property can be read. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-canSetProperty"></span>[`canSetProperty()`](/docs/api/yii/base/baseobject/index.md#method-canSetProperty) | Returns a value indicating whether a property can be set. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-className"></span>[`className()`](/docs/api/yii/base/baseobject/index.md#method-className) static | Returns the fully qualified name of this class. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| [`createUrl()`](#method-createUrl) | Creates the URL suitable for pagination with the specified page number. | `Pagination` |
| [`getLimit()`](#method-getLimit) |  | `Pagination` |
| [`getLinks()`](#method-getLinks) | Returns a whole set of links for navigating to the first, last, next and previous pages. | `Pagination` |
| [`getOffset()`](#method-getOffset) |  | `Pagination` |
| [`getPage()`](#method-getPage) | Returns the zero-based current page number. | `Pagination` |
| [`getPageCount()`](#method-getPageCount) |  | `Pagination` |
| [`getPageSize()`](#method-getPageSize) | Returns the number of items per page. | `Pagination` |
| <span id="method-hasMethod"></span>[`hasMethod()`](/docs/api/yii/base/baseobject/index.md#method-hasMethod) | Returns a value indicating whether a method is defined. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-hasProperty"></span>[`hasProperty()`](/docs/api/yii/base/baseobject/index.md#method-hasProperty) | Returns a value indicating whether a property is defined. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-init"></span>[`init()`](/docs/api/yii/base/baseobject/index.md#method-init) | Initializes the object. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| [`setPage()`](#method-setPage) | Sets the current page number. | `Pagination` |
| [`setPageSize()`](#method-setPageSize) |  | `Pagination` |
| [`getQueryParam()`](#method-getQueryParam) protected | Returns the value of the specified query parameter. | `Pagination` |
| [`resolveRoute()`](#method-resolveRoute) protected | Resolves the target route from [`$route`](/docs/api/yii/data/pagination/index.md#property-route), the active controller, or [`Application::$requestedRoute`](/docs/api/yii/base/application/index.md#property-requestedRoute). | `Pagination` |

## Constants

| Constant | Value | Description | Defined by |
| --- | --- | --- | --- |
| <span id="const-LINK_NEXT"></span>`LINK_NEXT` | `'next'` |  | `Pagination` |
| <span id="const-LINK_PREV"></span>`LINK_PREV` | `'prev'` |  | `Pagination` |
| <span id="const-LINK_FIRST"></span>`LINK_FIRST` | `'first'` |  | `Pagination` |
| <span id="const-LINK_LAST"></span>`LINK_LAST` | `'last'` |  | `Pagination` |

## Property details

### $defaultPageSize <span id="property-defaultPageSize"></span>

```php
public int $defaultPageSize = 20
```

The default page size.

This property will be returned by [`$pageSize`](/docs/api/yii/data/pagination/index.md#property-pageSize) when page size
cannot be determined by [`$pageSizeParam`](/docs/api/yii/data/pagination/index.md#property-pageSizeParam) from [`$params`](/docs/api/yii/data/pagination/index.md#property-params).

### $forcePageParam <span id="property-forcePageParam"></span>

```php
public bool $forcePageParam = true
```

Whether to always have the page parameter in the URL created by [`createUrl()`](/docs/api/yii/data/pagination/index.md#method-createUrl).

If false and [`$page`](/docs/api/yii/data/pagination/index.md#property-page) is 0, the page parameter will not be put in the URL.

### $limit <span id="property-limit"></span>

```php
public int $limit
```

The limit of the data.

This may be used to set the LIMIT value for a SQL
statement for fetching the current page of data. Note that if the page size is infinite, a value -1 will be
returned.

**Access**

Read-only (virtual property).

### $links <span id="property-links"></span>

```php
public array $links
```

The links for navigational purpose.

The array keys specify the purpose of the
links (e.g. [`LINK_FIRST`](/docs/api/yii/data/pagination/index.md#const-LINK_FIRST)), and the array values are the corresponding URLs.

**Access**

Read-only (virtual property).

### $offset <span id="property-offset"></span>

```php
public int $offset
```

The offset of the data.

This may be used to set the OFFSET value for a SQL
statement for fetching the current page of data.

**Access**

Read-only (virtual property).

### $pageSize <span id="property-pageSize"></span>

```php
public int $pageSize
```

The number of items per page.

If it is less than 1, it means the page size is
infinite, and thus a single page contains all items.

### $pageSizeLimit <span id="property-pageSizeLimit"></span>

```php
public array|false $pageSizeLimit = [1, 50]
```

The page size limits.

The first array element defines the minimum page size, and the second
the maximum page size. If this is false, it means [`$pageSize`](/docs/api/yii/data/pagination/index.md#property-pageSize) should always return the value of [`$defaultPageSize`](/docs/api/yii/data/pagination/index.md#property-defaultPageSize).

### $params <span id="property-params"></span>

```php
public array|null $params = null
```

Parameters (name => value) that should be used to obtain the current page number and to create new pagination URLs.

If not set, all parameters from $_GET will be used instead.

In order to add hash to all links use `array_merge($_GET, ['#' => 'my-hash'])`.

The array element indexed by [`$pageParam`](/docs/api/yii/data/pagination/index.md#property-pageParam) is considered to be the current page number (defaults to 0);
while the element indexed by [`$pageSizeParam`](/docs/api/yii/data/pagination/index.md#property-pageSizeParam) is treated as the page size (defaults to [`$defaultPageSize`](/docs/api/yii/data/pagination/index.md#property-defaultPageSize)).

### $route <span id="property-route"></span>

```php
public string|null $route = null
```

The route of the controller action for displaying the paged contents.

If not set, it means using the currently requested route.

### $urlManager <span id="property-urlManager"></span>

```php
public yii\web\UrlManager|null $urlManager = null
```

The URL manager used for creating pagination URLs.

If not set,
the "urlManager" application component will be used.

### $validatePage <span id="property-validatePage"></span>

```php
public bool $validatePage = true
```

Whether to check if [`$page`](/docs/api/yii/data/pagination/index.md#property-page) is within valid range.

When this property is true, the value of [`$page`](/docs/api/yii/data/pagination/index.md#property-page) will always be between 0 and ([`$pageCount`](/docs/api/yii/data/pagination/index.md#property-pageCount)-1).
Because [`$pageCount`](/docs/api/yii/data/pagination/index.md#property-pageCount) relies on the correct value of [`$totalCount`](/docs/api/yii/data/pagination/index.md#property-totalCount) which may not be available
in some cases (e.g. MongoDB), you may want to set this property to be false to disable the page
number validation. By doing so, [`$page`](/docs/api/yii/data/pagination/index.md#property-page) will return the value indexed by [`$pageParam`](/docs/api/yii/data/pagination/index.md#property-pageParam) in [`$params`](/docs/api/yii/data/pagination/index.md#property-params).

## Method details

### createUrl() <span id="method-createUrl"></span>

```php
public function createUrl(int $page, int|null $pageSize = null, bool $absolute = false): string
```

Creates the URL suitable for pagination with the specified page number.

This method is mainly called by pagers when creating URLs used to perform pagination.

The target route is determined by [`resolveRoute()`](/docs/api/yii/data/pagination/index.md#method-resolveRoute) when [`$route`](/docs/api/yii/data/pagination/index.md#property-route) is not configured.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$page` | `int` | The zero-based page number that the URL should point to. |
| `$pageSize` | `int\|null` | The number of items on each page. If not set, the value of [`$pageSize`](/docs/api/yii/data/pagination/index.md#property-pageSize) will be used. |
| `$absolute` | `bool` | Whether to create an absolute URL. Defaults to `false`. |

**Returns**

`string`: The created URL

**Throws**

- [`yii\base\InvalidConfigException`](/docs/api/yii/base/invalidconfigexception/index.md): if [`resolveRoute()`](/docs/api/yii/data/pagination/index.md#method-resolveRoute) cannot determine a route.

**See also**

- [`$params`](/docs/api/yii/data/pagination/index.md#property-params)
- [`$forcePageParam`](/docs/api/yii/data/pagination/index.md#property-forcePageParam)

### getLimit() <span id="method-getLimit"></span>

```php
public function getLimit(): int
```

**Returns**

`int`: The limit of the data. This may be used to set the LIMIT value for a SQL statement for fetching the current page of data. Note that if the page size is infinite, a value -1 will be returned.

### getLinks() <span id="method-getLinks"></span>

```php
public function getLinks(bool $absolute = false): array
```

Returns a whole set of links for navigating to the first, last, next and previous pages.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$absolute` | `bool` | Whether the generated URLs should be absolute. |

**Returns**

`array`: The links for navigational purpose. The array keys specify the purpose of the links (e.g. [`LINK_FIRST`](/docs/api/yii/data/pagination/index.md#const-LINK_FIRST)), and the array values are the corresponding URLs.

### getOffset() <span id="method-getOffset"></span>

```php
public function getOffset(): int
```

**Returns**

`int`: The offset of the data. This may be used to set the OFFSET value for a SQL statement for fetching the current page of data.

### getPage() <span id="method-getPage"></span>

```php
public function getPage(bool $recalculate = false): int
```

Returns the zero-based current page number.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$recalculate` | `bool` | Whether to recalculate the current page based on the page size and item count. |

**Returns**

`int`: The zero-based current page number.

### getPageCount() <span id="method-getPageCount"></span>

```php
public function getPageCount(): int
```

**Returns**

`int`: Number of pages

### getPageSize() <span id="method-getPageSize"></span>

```php
public function getPageSize(): int
```

Returns the number of items per page.

By default, this method will try to determine the page size by [`$pageSizeParam`](/docs/api/yii/data/pagination/index.md#property-pageSizeParam) in [`$params`](/docs/api/yii/data/pagination/index.md#property-params).
If the page size cannot be determined this way, [`$defaultPageSize`](/docs/api/yii/data/pagination/index.md#property-defaultPageSize) will be returned.

**Returns**

`int`: The number of items per page. If it is less than 1, it means the page size is infinite, and thus a single page contains all items.

**See also**

- [`$pageSizeLimit`](/docs/api/yii/data/pagination/index.md#property-pageSizeLimit)

### setPage() <span id="method-setPage"></span>

```php
public function setPage(int $value, bool $validatePage = false): mixed
```

Sets the current page number.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$value` | `int` | The zero-based index of the current page. |
| `$validatePage` | `bool` | Whether to validate the page number. Note that in order to validate the page number, both [`$validatePage`](/docs/api/yii/data/pagination/index.md#property-validatePage) and this parameter must be true. |

**Returns**

`mixed`

### setPageSize() <span id="method-setPageSize"></span>

```php
public function setPageSize(int $value, bool $validatePageSize = false): mixed
```

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$value` | `int` | The number of items per page. |
| `$validatePageSize` | `bool` | Whether to validate page size. |

**Returns**

`mixed`

### getQueryParam() <span id="method-getQueryParam"></span>

```php
protected function getQueryParam(string $name, string|null $defaultValue = null): string|null
```

Returns the value of the specified query parameter.

This method returns the named parameter value from [`$params`](/docs/api/yii/data/pagination/index.md#property-params). Null is returned if the value does not exist.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$name` | `string` | The parameter name |
| `$defaultValue` | `string\|null` | The value to be returned when the specified parameter does not exist in [`$params`](/docs/api/yii/data/pagination/index.md#property-params). |

**Returns**

`string|null`: The parameter value

### resolveRoute() <span id="method-resolveRoute"></span>

```php
protected function resolveRoute(): string
```

Resolves the target route from [`$route`](/docs/api/yii/data/pagination/index.md#property-route), the active controller, or [`Application::$requestedRoute`](/docs/api/yii/base/application/index.md#property-requestedRoute).

The `requestedRoute` fallback supports standalone actions where no controller is hosting the request.

**Returns**

`string`: The resolved route.

**Throws**

- [`yii\base\InvalidConfigException`](/docs/api/yii/base/invalidconfigexception/index.md): if no route can be resolved.