Pagination

API reference › yii › data › Pagination

class	yii\data\Pagination
Extends	yii\base\BaseObject
Implements	yii\web\Linkable, yii\base\Configurable
Since	2.0
Source	framework/data/Pagination.php

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, page size, current page, etc. These information can be passed to pagers 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.

Properties

Property	Type	Description	Defined by
$defaultPageSize	int	The default page size. Default: 20.	Pagination
$forcePageParam	bool	Whether to always have the page parameter in the URL created by createUrl(). Default: true.	Pagination
$limit read-only	int	The limit of the data.	Pagination
$links read-only	array	The links for navigational purpose.	Pagination
$offset read-only	int	The offset of the data.	Pagination
$page	int	The zero-based current page number.	Pagination
$pageCount read-only	int	Number of pages.	Pagination
$pageParam	string	Name of the parameter storing the current page index. Default: 'page'.	Pagination
$pageSize	int	The number of items per page.	Pagination
$pageSizeLimit	array|false	The page size limits. Default: [1, 50].	Pagination
$pageSizeParam	string	Name of the parameter storing the page size. Default: 'per-page'.	Pagination
$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	string|null	The route of the controller action for displaying the paged contents. Default: null.	Pagination
$totalCount	int	Total number of items. Default: 0.	Pagination
$urlManager	yii\web\UrlManager|null	The URL manager used for creating pagination URLs. Default: null.	Pagination
$validatePage	bool	Whether to check if $page is within valid range. Default: true.	Pagination

Methods

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

Constants

Constant	Value	Description	Defined by
LINK_NEXT	'next'		Pagination
LINK_PREV	'prev'		Pagination
LINK_FIRST	'first'		Pagination
LINK_LAST	'last'		Pagination

Property details

$defaultPageSize

public int $defaultPageSize = 20

The default page size.

This property will be returned by $pageSize when page size cannot be determined by $pageSizeParam from $params.

$forcePageParam

public bool $forcePageParam = true

Whether to always have the page parameter in the URL created by createUrl().

If false and $page is 0, the page parameter will not be put in the URL.

$limit

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

public array $links

The links for navigational purpose.

The array keys specify the purpose of the links (e.g. LINK_FIRST), and the array values are the corresponding URLs.

Access

Read-only (virtual property).

$offset

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

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

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 should always return the value of $defaultPageSize.

$params

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 is considered to be the current page number (defaults to 0); while the element indexed by $pageSizeParam is treated as the page size (defaults to $defaultPageSize).

$route

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

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

public bool $validatePage = true

Whether to check if $page is within valid range.

When this property is true, the value of $page will always be between 0 and ($pageCount-1). Because $pageCount relies on the correct value of $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 will return the value indexed by $pageParam in $params.

Method details

createUrl()

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() when $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 will be used.
$absolute	bool	Whether to create an absolute URL. Defaults to false.

Returns

string: The created URL

Throws

• yii\base\InvalidConfigException: if resolveRoute() cannot determine a route.

See also

• $params
• $forcePageParam

getLimit()

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()

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), and the array values are the corresponding URLs.

getOffset()

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()

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()

public function getPageCount(): int

Returns

int: Number of pages

getPageSize()

public function getPageSize(): int

Returns the number of items per page.

By default, this method will try to determine the page size by $pageSizeParam in $params. If the page size cannot be determined this way, $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

setPage()

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 and this parameter must be true.

Returns

mixed

setPageSize()

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()

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. 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.

Returns

string|null: The parameter value

resolveRoute()

protected function resolveRoute(): string

Resolves the target route from $route, the active controller, or Application::$requestedRoute.

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

Returns

string: The resolved route.

Throws

• yii\base\InvalidConfigException: if no route can be resolved.