HumHub Documentation (unofficial)

Pagination extends BaseObject
in package
implements Linkable

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 [[totalCount|total item count]], [[pageSize|page size]], [[page|current page]], etc. These information can be passed to [[\yii\widgets\LinkPager|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.

Tags
author

Qiang Xue qiang.xue@gmail.com

since
2.0

Table of Contents

Interfaces

Linkable
Linkable is the interface that should be implemented by classes that typically represent locatable resources.

Constants

LINK_FIRST  = 'first'
LINK_LAST  = 'last'
LINK_NEXT  = 'next'
LINK_PREV  = 'prev'

Properties

$defaultPageSize  : int
$forcePageParam  : bool
$limit  : int
$links  : array<string|int, mixed>
$offset  : int
$page  : int
$pageCount  : int
$pageParam  : string
$pageSize  : int
$pageSizeLimit  : array<string|int, mixed>|false
$pageSizeParam  : string
$params  : array<string|int, mixed>|null
$route  : string|null
$totalCount  : int
$urlManager  : UrlManager|null
$validatePage  : bool
$_page  : mixed
$_pageSize  : int
$_totalCount  : Closure|int

Methods

__call()  : mixed
Calls the named method which is not a class method.
__construct()  : mixed
Constructor.
__get()  : mixed
Returns the value of an object property.
__isset()  : bool
Checks if a property is set, i.e. defined and not null.
__set()  : mixed
Sets value of an object property.
__unset()  : mixed
Sets an object property to null.
canGetProperty()  : bool
Returns a value indicating whether a property can be read.
canSetProperty()  : bool
Returns a value indicating whether a property can be set.
className()  : string
Returns the fully qualified name of this class.
createUrl()  : string
Creates the URL suitable for pagination with the specified page number.
getLimit()  : int
getLinks()  : array<string|int, mixed>
Returns a whole set of links for navigating to the first, last, next and previous pages.
getOffset()  : int
getPage()  : int
Returns the zero-based current page number.
getPageCount()  : int
getPageSize()  : int
Returns the number of items per page.
getTotalCount()  : int
hasMethod()  : bool
Returns a value indicating whether a method is defined.
hasProperty()  : bool
Returns a value indicating whether a property is defined.
init()  : mixed
Initializes the object.
setPage()  : mixed
Sets the current page number.
setPageSize()  : mixed
setTotalCount()  : mixed
getQueryParam()  : string|null
Returns the value of the specified query parameter.

Constants

Properties

$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 read-only

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.

$links read-only

public array<string|int, mixed> $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.

$offset read-only

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.

$page

public int $page

The zero-based current page number.

$pageCount read-only

public int $pageCount

Number of pages.

$pageParam

public string $pageParam = 'page'

name of the parameter storing the current page index.

Tags
see
params

$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<string|int, mixed>|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]].

$pageSizeParam

public string $pageSizeParam = 'per-page'

name of the parameter storing the page size.

Tags
see
params

$params

public array<string|int, mixed>|null $params

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

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

$totalCount

public int $totalCount

total number of items.

$urlManager

public UrlManager|null $urlManager

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

$_pageSize

private int $_pageSize

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

$_totalCount

private Closure|int $_totalCount = 0

total number of items or closure returning it.

Methods

__call()

Calls the named method which is not a class method.

public __call(string $name, array<string|int, mixed> $params) : mixed

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.

Parameters
$name : string

the method name

$params : array<string|int, mixed>

method parameters

Tags
throws
UnknownMethodException

when calling unknown method

Return values
mixed —

the method return value

__construct()

Constructor.

public __construct([array<string|int, mixed> $config = [] ]) : mixed

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.
Parameters
$config : array<string|int, mixed> = []

name-value pairs that will be used to initialize the object properties

__get()

Returns the value of an object property.

public __get(string $name) : mixed

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

Parameters
$name : string

the property name

Tags
throws
UnknownPropertyException

if the property is not defined

throws
InvalidCallException

if the property is write-only

see
__set()
Return values
mixed —

the property value

__isset()

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

public __isset(string $name) : bool

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.

Parameters
$name : string

the property name or the event name

Tags
see
https://www.php.net/manual/en/function.isset.php
Return values
bool —

whether the named property is set (not null).

__set()

Sets value of an object property.

public __set(string $name, mixed $value) : mixed

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

Parameters
$name : string

the property name or the event name

$value : mixed

the property value

Tags
throws
UnknownPropertyException

if the property is not defined

throws
InvalidCallException

if the property is read-only

see
__get()

__unset()

Sets an object property to null.

public __unset(string $name) : mixed

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.

Parameters
$name : string

the property name

Tags
throws
InvalidCallException

if the property is read only.

see
https://www.php.net/manual/en/function.unset.php

canGetProperty()

Returns a value indicating whether a property can be read.

public canGetProperty(string $name[, bool $checkVars = true ]) : bool

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);
Parameters
$name : string

the property name

$checkVars : bool = true

whether to treat member variables as properties

Tags
see
canSetProperty()
Return values
bool —

whether the property can be read

canSetProperty()

Returns a value indicating whether a property can be set.

public canSetProperty(string $name[, bool $checkVars = true ]) : bool

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);
Parameters
$name : string

the property name

$checkVars : bool = true

whether to treat member variables as properties

Tags
see
canGetProperty()
Return values
bool —

whether the property can be written

className()

Returns the fully qualified name of this class.

public static className() : string
Tags
deprecated

since 2.0.14. On PHP >=5.5, use ::class instead.

Return values
string —

the fully qualified name of this class.

createUrl()

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

public createUrl(int $page[, int|null $pageSize = null ][, bool $absolute = false ]) : string

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

Parameters
$page : int

the zero-based page number that the URL should point to.

$pageSize : int|null = null

the number of items on each page. If not set, the value of [[pageSize]] will be used.

$absolute : bool = false

whether to create an absolute URL. Defaults to false.

Tags
see
params
see
forcePageParam
Return values
string —

the created URL

getLimit()

public getLimit() : int
Return values
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()

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

public getLinks([bool $absolute = false ]) : array<string|int, mixed>
Parameters
$absolute : bool = false

whether the generated URLs should be absolute.

Return values
array<string|int, mixed> —

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 getOffset() : int
Return values
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()

Returns the zero-based current page number.

public getPage([bool $recalculate = false ]) : int
Parameters
$recalculate : bool = false

whether to recalculate the current page based on the page size and item count.

Return values
int —

the zero-based current page number.

getPageCount()

public getPageCount() : int
Return values
int —

number of pages

getPageSize()

Returns the number of items per page.

public getPageSize() : int

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.

Tags
see
pageSizeLimit
Return values
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.

getTotalCount()

public getTotalCount() : int
Return values
int —

total number of items.

hasMethod()

Returns a value indicating whether a method is defined.

public hasMethod(string $name) : bool

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

Parameters
$name : string

the method name

Return values
bool —

whether the method is defined

hasProperty()

Returns a value indicating whether a property is defined.

public hasProperty(string $name[, bool $checkVars = true ]) : bool

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);
Parameters
$name : string

the property name

$checkVars : bool = true

whether to treat member variables as properties

Tags
see
canGetProperty()
see
canSetProperty()
Return values
bool —

whether the property is defined

init()

Initializes the object.

public init() : mixed

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

setPage()

Sets the current page number.

public setPage(int $value[, bool $validatePage = false ]) : mixed
Parameters
$value : int

the zero-based index of the current page.

$validatePage : bool = false

whether to validate the page number. Note that in order to validate the page number, both [[validatePage]] and this parameter must be true.

setPageSize()

public setPageSize(int $value[, bool $validatePageSize = false ]) : mixed
Parameters
$value : int

the number of items per page.

$validatePageSize : bool = false

whether to validate page size.

setTotalCount()

public setTotalCount(Closure|int $count) : mixed
Parameters
$count : Closure|int

getQueryParam()

Returns the value of the specified query parameter.

protected getQueryParam(string $name[, string|null $defaultValue = null ]) : string|null

This method returns the named parameter value from [[params]]. Null is returned if the value does not exist.

Parameters
$name : string

the parameter name

$defaultValue : string|null = null

the value to be returned when the specified parameter does not exist in [[params]].

Return values
string|null —

the parameter value


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results