# Class yii\data\Pagination

Inheritance | yii\data\Pagination » yii\base\BaseObject
Implements | yii\base\Configurable, yii\web\Linkable
Available since version | 2.0
Source Code | https://github.com/yiisoft/yii2/blob/master/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.

## Public Properties

Hide inherited properties

Property | Type | Description | Defined By
--- | --- | --- | ---
$defaultPageSize | integer | The default page size. | yii\data\Pagination
$forcePageParam | boolean | Whether to always have the page parameter in the URL created by createUrl(). | yii\data\Pagination
$limit | integer | The limit of the data. | yii\data\Pagination
$links | array | The links for navigational purpose. | yii\data\Pagination
$offset | integer | The offset of the data. | yii\data\Pagination
$page | integer | The zero-based current page number. | yii\data\Pagination
$pageCount | integer | Number of pages. | yii\data\Pagination
$pageParam | string | Name of the parameter storing the current page index. | yii\data\Pagination
$pageSize | integer | The number of items per page. | yii\data\Pagination
$pageSizeLimit | array|false | The page size limits. | yii\data\Pagination
$pageSizeParam | string | Name of the parameter storing the page size. | yii\data\Pagination
$params | array|null | Parameters (name => value) that should be used to obtain the current page number and to create new pagination URLs. | yii\data\Pagination
$route | string|null | The route of the controller action for displaying the paged contents. | yii\data\Pagination
$totalCount | integer | Total number of items. | yii\data\Pagination
$urlManager | yii\web\UrlManager|null | The URL manager used for creating pagination URLs. | yii\data\Pagination
$validatePage | boolean | Whether to check if $page is within valid range. | yii\data\Pagination

## Public Methods

Hide inherited methods

Method | Description | Defined By
--- | --- | ---
__call() | Calls the named method which is not a class method. | yii\base\BaseObject
__construct() | Constructor. | 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() | Returns the fully qualified name of this class. | yii\base\BaseObject
createUrl() | Creates the URL suitable for pagination with the specified page number. | yii\data\Pagination
getLimit() |  | yii\data\Pagination
getLinks() | Returns a whole set of links for navigating to the first, last, next and previous pages. | yii\data\Pagination
getOffset() |  | yii\data\Pagination
getPage() | Returns the zero-based current page number. | yii\data\Pagination
getPageCount() |  | yii\data\Pagination
getPageSize() | Returns the number of items per page. | yii\data\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. | yii\data\Pagination
setPageSize() |  | yii\data\Pagination

## Protected Methods

Hide inherited methods

Method | Description | Defined By
--- | --- | ---
getQueryParam() | Returns the value of the specified query parameter. | yii\data\Pagination

## Constants

Hide inherited constants

Constant | Value | Description | Defined By
--- | --- | --- | ---
LINK_FIRST | 'first' |  | yii\data\Pagination
LINK_LAST | 'last' |  | yii\data\Pagination
LINK_NEXT | 'next' |  | yii\data\Pagination
LINK_PREV | 'prev' |  | yii\data\Pagination

## Property Details

Hide inherited properties

$defaultPageSize public property

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

public integer $defaultPageSize = 20
$forcePageParam public property

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.

public boolean $forcePageParam = true
$limit public property

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.

public integer $limit = null
$links public property

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.

public array $links = null
$offset public property

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.

public integer $offset = null
$page public property

The zero-based current page number.

public integer $page = null
$pageCount public property

Number of pages.

public integer $pageCount = null
$pageParam public property

Name of the parameter storing the current page index.

See also $params.

public string $pageParam = 'page'
$pageSize public property

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.

public integer $pageSize = null
$pageSizeLimit public property

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.

public array|false $pageSizeLimit = [
1,
50,
]
$pageSizeParam public property

Name of the parameter storing the page size.

See also $params.

public string $pageSizeParam = 'per-page'
$params public property

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

public array|null $params = null
$route public property

The route of the controller action for displaying the paged contents. If not set, it means using the currently requested route.

public string|null $route = null
$totalCount public property

Total number of items.

public integer $totalCount = 0
$urlManager public property

The URL manager used for creating pagination URLs. If not set, the "urlManager" application component will be used.

public yii\web\UrlManager|null $urlManager = null
$validatePage public property

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.

public boolean $validatePage = true

## Method Details

Hide inherited methods

__call() public method

Defined in: yii\base\BaseObject::__call()

Calls the named method which is not a class method.

Do not call this method directly as it is a PHP magic method that will be implicitly called when an unknown method is being invoked.

public mixed __call ( $name, $params )
$name | string | The method name
$params | array | Method parameters
return | mixed | The method return value
throws | yii\base\UnknownMethodException | when calling unknown method

Source code

                    public function __call($name, $params)
    {
        throw new UnknownMethodException('Calling unknown method: ' . get_class($this) . "::$name()");
    }

__construct() public method

Defined in: yii\base\BaseObject::__construct()

Constructor.

The default implementation does two things:

- Initializes the object with the given configuration `$config`.
- Call init().

If this method is overridden in a child class, it is recommended that

- the last parameter of the constructor is a configuration array, like `$config` here.
- call the parent implementation at the end of the constructor.

public void __construct ( $config = [] )
$config | array | Name-value pairs that will be used to initialize the object properties

Source code

                    public function __construct($config = [])
    {
        if (!empty($config)) {
            Yii::configure($this, $config);
        }
        $this->init();
    }

__get() public method

Defined in: yii\base\BaseObject::__get()

Returns the value of an object property.

Do not call this method directly as it is a PHP magic method that will be implicitly called when executing `$value = $object->property;`.

See also __set().

public mixed __get ( $name )
$name | string | The property name
return | mixed | The property value
throws | yii\base\UnknownPropertyException | if the property is not defined
throws | yii\base\InvalidCallException | if the property is write-only

Source code

                    public function __get($name)
    {
        $getter = 'get' . $name;
        if (method_exists($this, $getter)) {
            return $this->$getter();
        } elseif (method_exists($this, 'set' . $name)) {
            throw new InvalidCallException('Getting write-only property: ' . get_class($this) . '::' . $name);
        }
        throw new UnknownPropertyException('Getting unknown property: ' . get_class($this) . '::' . $name);
    }

__isset() public method

Defined in: yii\base\BaseObject::__isset()

Checks if a property is set, i.e. defined and not null.

Do not call this method directly as it is a PHP magic method that will be implicitly called when executing `isset($object->property)`.

Note that if the property is not defined, false will be returned.

See also https://www.php.net/manual/en/function.isset.php.

public boolean __isset ( $name )
$name | string | The property name or the event name
return | boolean | Whether the named property is set (not null).

Source code

                    public function __isset($name)
    {
        $getter = 'get' . $name;
        if (method_exists($this, $getter)) {
            return $this->$getter() !== null;
        }
        return false;
    }

__set() public method

Defined in: yii\base\BaseObject::__set()

Sets value of an object property.

Do not call this method directly as it is a PHP magic method that will be implicitly called when executing `$object->property = $value;`.

See also __get().

public void __set ( $name, $value )
$name | string | The property name or the event name
$value | mixed | The property value
throws | yii\base\UnknownPropertyException | if the property is not defined
throws | yii\base\InvalidCallException | if the property is read-only

Source code

                    public function __set($name, $value)
    {
        $setter = 'set' . $name;
        if (method_exists($this, $setter)) {
            $this->$setter($value);
        } elseif (method_exists($this, 'get' . $name)) {
            throw new InvalidCallException('Setting read-only property: ' . get_class($this) . '::' . $name);
        } else {
            throw new UnknownPropertyException('Setting unknown property: ' . get_class($this) . '::' . $name);
        }
    }

__unset() public method

Defined in: yii\base\BaseObject::__unset()

Sets an object property to null.

Do not call this method directly as it is a PHP magic method that will be implicitly called when executing `unset($object->property)`.

Note that if the property is not defined, this method will do nothing. If the property is read-only, it will throw an exception.

See also https://www.php.net/manual/en/function.unset.php.

public void __unset ( $name )
$name | string | The property name
throws | yii\base\InvalidCallException | if the property is read only.

Source code

                    public function __unset($name)
    {
        $setter = 'set' . $name;
        if (method_exists($this, $setter)) {
            $this->$setter(null);
        } elseif (method_exists($this, 'get' . $name)) {
            throw new InvalidCallException('Unsetting read-only property: ' . get_class($this) . '::' . $name);
        }
    }

canGetProperty() public method

Defined in: yii\base\BaseObject::canGetProperty()

Returns a value indicating whether a property can be read.

A property is readable if:

- the class has a getter method associated with the specified name (in this case, property name is case-insensitive);
- the class has a member variable with the specified name (when `$checkVars` is true);

See also canSetProperty().

public boolean canGetProperty ( $name, $checkVars = true )
$name | string | The property name
$checkVars | boolean | Whether to treat member variables as properties
return | boolean | Whether the property can be read

Source code

                    public function canGetProperty($name, $checkVars = true)
    {
        return method_exists($this, 'get' . $name) || $checkVars && property_exists($this, $name);
    }

canSetProperty() public method

Defined in: yii\base\BaseObject::canSetProperty()

Returns a value indicating whether a property can be set.

A property is writable if:

- the class has a setter method associated with the specified name (in this case, property name is case-insensitive);
- the class has a member variable with the specified name (when `$checkVars` is true);

See also canGetProperty().

public boolean canSetProperty ( $name, $checkVars = true )
$name | string | The property name
$checkVars | boolean | Whether to treat member variables as properties
return | boolean | Whether the property can be written

Source code

                    public function canSetProperty($name, $checkVars = true)
    {
        return method_exists($this, 'set' . $name) || $checkVars && property_exists($this, $name);
    }

className() public static method
Deprecated since 2.0.14. On PHP >=5.5, use `::class` instead.

Defined in: yii\base\BaseObject::className()

Returns the fully qualified name of this class.

public static string className ( )
return | string | The fully qualified name of this class.

Source code

                    public static function className()
    {
        return get_called_class();
    }

createUrl() public method

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.

See also:

- $params
- $forcePageParam

public string createUrl ( $page, $pageSize = null, $absolute = false )
$page | integer | The zero-based page number that the URL should point to.
$pageSize | integer|null | The number of items on each page. If not set, the value of $pageSize will be used.
$absolute | boolean | Whether to create an absolute URL. Defaults to `false`.
return | string | The created URL

Source code

                    public function createUrl($page, $pageSize = null, $absolute = false)
    {
        $page = (int) $page;
        $pageSize = (int) $pageSize;
        if (($params = $this->params) === null) {
            $request = Yii::$app->getRequest();
            $params = $request instanceof Request ? $request->getQueryParams() : [];
        }
        if ($page > 0 || $page == 0 && $this->forcePageParam) {
            $params[$this->pageParam] = $page + 1;
        } else {
            unset($params[$this->pageParam]);
        }
        if ($pageSize <= 0) {
            $pageSize = $this->getPageSize();
        }
        if ($pageSize != $this->defaultPageSize) {
            $params[$this->pageSizeParam] = $pageSize;
        } else {
            unset($params[$this->pageSizeParam]);
        }
        $params[0] = $this->route === null ? Yii::$app->controller->getRoute() : $this->route;
        $urlManager = $this->urlManager === null ? Yii::$app->getUrlManager() : $this->urlManager;
        if ($absolute) {
            return $urlManager->createAbsoluteUrl($params);
        }
        return $urlManager->createUrl($params);
    }

getLimit() public method

public integer getLimit ( )
return | integer | 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.

Source code

                    public function getLimit()
    {
        $pageSize = $this->getPageSize();
        return $pageSize < 1 ? -1 : $pageSize;
    }

getLinks() public method

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

public array getLinks ( $absolute = false )
$absolute | boolean | Whether the generated URLs should be absolute.
return | 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.

Source code

                    public function getLinks($absolute = false)
    {
        $currentPage = $this->getPage();
        $pageCount = $this->getPageCount();
        $links = [Link::REL_SELF => $this->createUrl($currentPage, null, $absolute)];
        if ($pageCount > 0) {
            $links[self::LINK_FIRST] = $this->createUrl(0, null, $absolute);
            $links[self::LINK_LAST] = $this->createUrl($pageCount - 1, null, $absolute);
            if ($currentPage > 0) {
                $links[self::LINK_PREV] = $this->createUrl($currentPage - 1, null, $absolute);
            }
            if ($currentPage < $pageCount - 1) {
                $links[self::LINK_NEXT] = $this->createUrl($currentPage + 1, null, $absolute);
            }
        }
        return $links;
    }

getOffset() public method

public integer getOffset ( )
return | integer | 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.

Source code

                    public function getOffset()
    {
        $pageSize = $this->getPageSize();
        return $pageSize < 1 ? 0 : $this->getPage() * $pageSize;
    }

getPage() public method

Returns the zero-based current page number.

public integer getPage ( $recalculate = false )
$recalculate | boolean | Whether to recalculate the current page based on the page size and item count.
return | integer | The zero-based current page number.

Source code

                    public function getPage($recalculate = false)
    {
        if ($this->_page === null || $recalculate) {
            $page = (int) $this->getQueryParam($this->pageParam, 1) - 1;
            $this->setPage($page, true);
        }
        return $this->_page;
    }

getPageCount() public method

public integer getPageCount ( )
return | integer | Number of pages

Source code

                    public function getPageCount()
    {
        $pageSize = $this->getPageSize();
        if ($pageSize < 1) {
            return $this->totalCount > 0 ? 1 : 0;
        }
        $totalCount = $this->totalCount < 0 ? 0 : (int) $this->totalCount;
        return (int) (($totalCount + $pageSize - 1) / $pageSize);
    }

getPageSize() public method

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.

See also $pageSizeLimit.

public integer getPageSize ( )
return | integer | 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.

Source code

                    public function getPageSize()
    {
        if ($this->_pageSize === null) {
            if (empty($this->pageSizeLimit) || !isset($this->pageSizeLimit[0], $this->pageSizeLimit[1])) {
                $pageSize = $this->defaultPageSize;
                $this->setPageSize($pageSize);
            } else {
                $pageSize = (int) $this->getQueryParam($this->pageSizeParam, $this->defaultPageSize);
                $this->setPageSize($pageSize, true);
            }
        }
        return $this->_pageSize;
    }

getQueryParam() protected method

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.

protected string|null getQueryParam ( $name, $defaultValue = null )
$name | string | The parameter name
$defaultValue | string|null | The value to be returned when the specified parameter does not exist in $params.
return | string|null | The parameter value

Source code

                    protected function getQueryParam($name, $defaultValue = null)
    {
        if (($params = $this->params) === null) {
            $request = Yii::$app->getRequest();
            $params = $request instanceof Request ? $request->getQueryParams() : [];
        }
        return isset($params[$name]) && is_scalar($params[$name]) ? $params[$name] : $defaultValue;
    }

hasMethod() public method

Defined in: yii\base\BaseObject::hasMethod()

Returns a value indicating whether a method is defined.

The default implementation is a call to php function `method_exists()`. You may override this method when you implemented the php magic method `__call()`.

public boolean hasMethod ( $name )
$name | string | The method name
return | boolean | Whether the method is defined

Source code

                    public function hasMethod($name)
    {
        return method_exists($this, $name);
    }

hasProperty() public method

Defined in: yii\base\BaseObject::hasProperty()

Returns a value indicating whether a property is defined.

A property is defined if:

- the class has a getter or setter method associated with the specified name (in this case, property name is case-insensitive);
- the class has a member variable with the specified name (when `$checkVars` is true);

See also:

- canGetProperty()
- canSetProperty()

public boolean hasProperty ( $name, $checkVars = true )
$name | string | The property name
$checkVars | boolean | Whether to treat member variables as properties
return | boolean | Whether the property is defined

Source code

                    public function hasProperty($name, $checkVars = true)
    {
        return $this->canGetProperty($name, $checkVars) || $this->canSetProperty($name, false);
    }

init() public method

Defined in: yii\base\BaseObject::init()

Initializes the object.

This method is invoked at the end of the constructor after the object is initialized with the given configuration.

public void init ( )

Source code

                    public function init()
    {
    }

setPage() public method

Sets the current page number.

public void setPage ( $value, $validatePage = false )
$value | integer | The zero-based index of the current page.
$validatePage | boolean | Whether to validate the page number. Note that in order to validate the page number, both $validatePage and this parameter must be true.

Source code

                    public function setPage($value, $validatePage = false)
    {
        if ($value === null) {
            $this->_page = null;
        } else {
            $value = (int) $value;
            if ($validatePage && $this->validatePage) {
                $pageCount = $this->getPageCount();
                if ($value >= $pageCount) {
                    $value = $pageCount - 1;
                }
            }
            if ($value < 0) {
                $value = 0;
            }
            $this->_page = $value;
        }
    }

setPageSize() public method

public void setPageSize ( $value, $validatePageSize = false )
$value | integer | The number of items per page.
$validatePageSize | boolean | Whether to validate page size.

Source code

                    public function setPageSize($value, $validatePageSize = false)
    {
        if ($value === null) {
            $this->_pageSize = null;
        } else {
            $value = (int) $value;
            if ($validatePageSize && isset($this->pageSizeLimit[0], $this->pageSizeLimit[1])) {
                if ($value < $this->pageSizeLimit[0]) {
                    $value = $this->pageSizeLimit[0];
                } elseif ($value > $this->pageSizeLimit[1]) {
                    $value = $this->pageSizeLimit[1];
                }
            }
            $this->_pageSize = $value;
        }
    }