Class PaginatorHelper

Pagination Helper class for easy generation of pagination links.

PaginationHelper encloses all methods needed when working with pagination.

Namespace: Cake\View\Helper
Link: https://book.cakephp.org/5/en/views/helpers/paginator.html

Property Summary

$Form public @property

Cake\View\Helper\FormHelper
$Html public @property

Cake\View\Helper\HtmlHelper
$Number public @property

Cake\View\Helper\NumberHelper
$Url public @property

Cake\View\Helper\UrlHelper
$_View protected

Cake\View\View

The View instance this helper is attached to
$_config protected

array<string, mixed>

Runtime config
$_configInitialized protected

bool

Whether the config property has already been configured with defaults
$_defaultConfig protected

array<string, mixed>

Default config for this class
$_templater protected

Cake\View\StringTemplate|null

StringTemplate instance.
$helperInstances protected

array<string,Cake\View\Helper>

Loaded helper instances.
$helpers protected

array

List of helpers used by this helper
$paginated protected

Cake\Datasource\Paging\PaginatedInterface

Paginated results

Method Summary

__construct() public

Constructor. Overridden to merge passed args with URL options.
__debugInfo() public

Returns an array that can be used to describe the internal state of this object.
__get() public

Lazy loads helpers.
_configDelete() protected

Deletes a single config key.
_configRead() protected

Reads a config key.
_configWrite() protected

Writes a config key.
_confirm() protected

Returns a string to be used as onclick handler for confirm dialogs.
_firstNumber() protected

Generates the first number for the paginator numbers() method.
_formatNumber() protected

Formats a number for the paginator number output.
_getNumbersStartAndEnd() protected

Calculates the start and end for the pagination numbers.
_lastNumber() protected

Generates the last number for the paginator numbers() method.
_modulusNumbers() protected

Generates the numbers for the paginator numbers() method.
_numbers() protected

Generates the numbers for the paginator numbers() method.
_removeAlias() protected

Remove alias if needed.
_toggledLink() protected

Generate an active/inactive link for next/prev methods.
addClass() public

Adds the given class to the element options
configShallow() public

Merge provided config with existing config. Unlike config() which does a recursive merge for nested keys, this method does a simple merge.
counter() public

Returns a counter string for the paged result set.
current() public

Gets the current page of the recordset for the given model
first() public

Returns a first or set of numbers for the first pages.
formatTemplate() public

Formats a template string with $data
generateUrl() public

Merges passed URL options with current pagination state to generate a pagination URL.
generateUrlParams() public

Merges passed URL options with current pagination state to generate a pagination URL.
getConfig() public

Returns the config.
getConfigOrFail() public

Returns the config for this specific key.
getTemplates() public

Gets templates to use or a specific template.
getView() public

Get the view instance this helper is bound to.
hasNext() public

Returns true if the given result set is not at the last page
hasPage() public

Returns true if the given result set has the page number given by $page
hasPrev() public

Returns true if the given result set is not at the first page
implementedEvents() public

Event listeners.
initialize() public

Constructor hook method.
last() public

Returns a last or set of numbers for the last pages.
limitControl() public

Dropdown select for pagination limit. This will generate a wrapping form.
meta() public

Returns the meta-links for a paginated result set.
next() public

Generates a "next" link for a set of paged records
numbers() public

Returns a set of numbers for the paged result set uses a modulus to decide how many numbers to show on each side of the current page (default: 8).
options() public

Sets default options for all pagination links
paginated() protected

Get pagination instance.
param() public

Convenience access to any of the paginator params.
params() public

Gets the current paging parameters from the resultset for the given model
prev() public

Generates a "previous" link for a set of paged records
setConfig() public

Sets the config.
setPaginated() public

Set paginated results.
setTemplates() public

Sets templates to use.
sort() public

Generates a sorting link. Sets named parameters for the sort and direction. Handles direction switching automatically.
sortDir() protected

Gets the current direction the recordset is sorted
templater() public

Returns the templater instance.
total() public

Gets the total number of pages in the recordset for the given model.

Method Detail

__construct() ¶ public

__construct(Cake\View\View $view, array<string, mixed> $config = [])

Constructor. Overridden to merge passed args with URL options.

Parameters

Cake\View\View $view: The View this helper is being attached to.
array<string, mixed> $config optional: Configuration settings for the helper.

__debugInfo() ¶ public

__debugInfo(): array<string, mixed>

Returns an array that can be used to describe the internal state of this object.

Returns

array<string, mixed>

__get() ¶ public

__get(string $name): Cake\View\Helper|null

Lazy loads helpers.

Parameters

string $name: Name of the property being accessed.

Returns

Cake\View\Helper|null

_configDelete() ¶ protected

_configDelete(string $key): void

Deletes a single config key.

Parameters

string $key: Key to delete.

Returns

void

Throws

Cake\Core\Exception\CakeException
if attempting to clobber existing config

_configRead() ¶ protected

_configRead(string|null $key): mixed

Reads a config key.

Parameters

string|null $key: Key to read.

Returns

mixed

_configWrite() ¶ protected

_configWrite(array<string, mixed>|string $key, mixed $value, string|bool $merge = false): void

Writes a config key.

Parameters

array<string, mixed>|string $key: Key to write to.
mixed $value: Value to write.
string|bool $merge optional: True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.

Returns

void

Throws

Cake\Core\Exception\CakeException
if attempting to clobber existing config

_confirm() ¶ protected

_confirm(string $okCode, string $cancelCode): string

Returns a string to be used as onclick handler for confirm dialogs.

Parameters

string $okCode: Code to be executed after user chose 'OK'
string $cancelCode: Code to be executed after user chose 'Cancel'

Returns

string

_firstNumber() ¶ protected

_firstNumber(string $ellipsis, array<string, mixed> $params, int $start, array<string, mixed> $options): string

Generates the first number for the paginator numbers() method.

Parameters

string $ellipsis: Ellipsis character.
array<string, mixed> $params: Params from the numbers() method.
int $start: Start number.
array<string, mixed> $options: Options from the numbers() method.

Returns

string

_formatNumber() ¶ protected

_formatNumber(Cake\View\StringTemplate $templater, array<string, mixed> $options): string

Formats a number for the paginator number output.

Parameters

Cake\View\StringTemplate $templater: StringTemplate instance.
array<string, mixed> $options: Options from the numbers() method.

Returns

string

_getNumbersStartAndEnd() ¶ protected

_getNumbersStartAndEnd(array<string, mixed> $params, array<string, mixed> $options): array

Calculates the start and end for the pagination numbers.

Parameters

array<string, mixed> $params: Params from the numbers() method.
array<string, mixed> $options: Options from the numbers() method.

Returns

array

_lastNumber() ¶ protected

_lastNumber(string $ellipsis, array<string, mixed> $params, int $end, array<string, mixed> $options): string

Generates the last number for the paginator numbers() method.

Parameters

string $ellipsis: Ellipsis character.
array<string, mixed> $params: Params from the numbers() method.
int $end: End number.
array<string, mixed> $options: Options from the numbers() method.

Returns

string

_modulusNumbers() ¶ protected

_modulusNumbers(Cake\View\StringTemplate $templater, array<string, mixed> $params, array<string, mixed> $options): string

Generates the numbers for the paginator numbers() method.

Parameters

Cake\View\StringTemplate $templater: StringTemplate instance.
array<string, mixed> $params: Params from the numbers() method.
array<string, mixed> $options: Options from the numbers() method.

Returns

string

_numbers() ¶ protected

_numbers(Cake\View\StringTemplate $templater, array<string, mixed> $params, array<string, mixed> $options): string

Generates the numbers for the paginator numbers() method.

Parameters

Cake\View\StringTemplate $templater: StringTemplate instance.
array<string, mixed> $params: Params from the numbers() method.
array<string, mixed> $options: Options from the numbers() method.

Returns

string

_removeAlias() ¶ protected

_removeAlias(string $field, ?string $alias = null): string

Remove alias if needed.

Parameters

string $field: Current field
?string $alias optional

Returns

string

_toggledLink() ¶ protected

_toggledLink(string|false $text, bool $enabled, array<string, mixed> $options, array<string, mixed> $templates): string

Generate an active/inactive link for next/prev methods.

Parameters

string|false $text: The enabled text for the link.
bool $enabled: Whether the enabled/disabled version should be created.
array<string, mixed> $options: An array of options from the calling method.
array<string, mixed> $templates: An array of templates with the 'active' and 'disabled' keys.

Returns

string

addClass() ¶ public

addClass(array<string, mixed> $options, string $class, string $key = 'class'): array<string, mixed>

Adds the given class to the element options

Parameters

array<string, mixed> $options: Array options/attributes to add a class to
string $class: The class name being added.
string $key optional: the key to use for class. Defaults to 'class'.

Returns

array<string, mixed>

configShallow() ¶ public

configShallow(array<string, mixed>|string $key, mixed|null $value = null): $this

Merge provided config with existing config. Unlike config() which does a recursive merge for nested keys, this method does a simple merge.

Setting a specific value:

$this->configShallow('key', $value);

Setting a nested value:

$this->configShallow('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->configShallow(['one' => 'value', 'another' => 'value']);

Parameters

array<string, mixed>|string $key: The key to set, or a complete array of configs.
mixed|null $value optional: The value to set.

Returns

$this

counter() ¶ public

counter(string $format = 'pages'): string

Returns a counter string for the paged result set.

Options

Parameters

string $format optional: The format string you want to use, defaults to 'pages' Which generates output like '1 of 5' set to 'range' to generate output like '1 - 3 of 13'. Can also be set to a custom string, containing the following placeholders {{page}}, {{pages}}, {{current}}, {{count}}, {{model}}, {{start}}, {{end}} and any custom content you would like.

Returns

string

Links

https://book.cakephp.org/5/en/views/helpers/paginator.html#creating-a-page-counter

current() ¶ public

current(): int

Gets the current page of the recordset for the given model

Returns

int

Links

https://book.cakephp.org/5/en/views/helpers/paginator.html#checking-the-pagination-state

first() ¶ public

first(string|int $first = '<< first', array<string, mixed> $options = []): string

Returns a first or set of numbers for the first pages.

echo $this->Paginator->first('< first');

Creates a single link for the first page. Will output nothing if you are on the first page.

echo $this->Paginator->first(3);

Will create links for the first 3 pages, once you get to the third or greater page. Prior to that nothing will be output.

Options:

escape Whether to HTML escape the text.
url An array of additional URL options to use for link generation.

Parameters

string|int $first optional: if string use as label for the link. If numeric, the number of page links you want at the beginning of the range.
array<string, mixed> $options optional: An array of options.

Returns

string

Links

https://book.cakephp.org/5/en/views/helpers/paginator.html#creating-jump-links

formatTemplate() ¶ public

formatTemplate(string $name, array<string, mixed> $data): string

Formats a template string with $data

Parameters

string $name: The template name.
array<string, mixed> $data: The data to insert.

Returns

string

generateUrl() ¶ public

generateUrl(array<string, mixed> $options = [], array $url = [], array<string, mixed> $urlOptions = []): string

Merges passed URL options with current pagination state to generate a pagination URL.

Url options:

escape: If false, the URL will be returned unescaped, do only use if it is manually escaped afterwards before being displayed.
fullBase: If true, the full base URL will be prepended to the result

Parameters

array<string, mixed> $options optional: Pagination options.
array $url optional: URL.
array<string, mixed> $urlOptions optional: Array of options

Returns

string

Links

https://book.cakephp.org/5/en/views/helpers/paginator.html#generating-pagination-urls

generateUrlParams() ¶ public

generateUrlParams(array<string, mixed> $options = [], array $url = []): array

Merges passed URL options with current pagination state to generate a pagination URL.

Parameters

array<string, mixed> $options optional: Pagination/URL options array
array $url optional: URL.

Returns

array

getConfig() ¶ public

getConfig(string|null $key = null, mixed $default = null): mixed

Returns the config.

Usage

Reading the whole config:

$this->getConfig();

Reading a specific value:

$this->getConfig('key');

Reading a nested value:

$this->getConfig('some.nested.key');

Reading with default value:

$this->getConfig('some-key', 'default-value');

Parameters

string|null $key optional: The key to get or null for the whole config.
mixed $default optional: The return value when the key does not exist.

Returns

mixed

getConfigOrFail() ¶ public

getConfigOrFail(string $key): mixed

Returns the config for this specific key.

The config value for this key must exist, it can never be null.

Parameters

string $key: The key to get.

Returns

mixed

Throws

InvalidArgumentException

getTemplates() ¶ public

getTemplates(string|null $template = null): array|string

Gets templates to use or a specific template.

Parameters

string|null $template optional: String for reading a specific template, null for all.

Returns

array|string

getView() ¶ public

getView(): Cake\View\View

Get the view instance this helper is bound to.

Returns

Cake\View\View

hasNext() ¶ public

hasNext(): bool

Returns true if the given result set is not at the last page

Returns

bool

Links

https://book.cakephp.org/5/en/views/helpers/paginator.html#checking-the-pagination-state

hasPage() ¶ public

hasPage(int $page = 1): bool

Returns true if the given result set has the page number given by $page

Parameters

int $page optional: The page number - if not set defaults to 1.

Returns

bool

Throws

InvalidArgumentException

Links

https://book.cakephp.org/5/en/views/helpers/paginator.html#checking-the-pagination-state

hasPrev() ¶ public

hasPrev(): bool

Returns true if the given result set is not at the first page

Returns

bool

Links

https://book.cakephp.org/5/en/views/helpers/paginator.html#checking-the-pagination-state

implementedEvents() ¶ public

implementedEvents(): array<string, mixed>

Event listeners.

By defining one of the callback methods a helper is assumed to be interested in the related event.

Override this method if you need to add non-conventional event listeners. Or if you want helpers to listen to non-standard events.

Returns

array<string, mixed>

initialize() ¶ public

initialize(array<string, mixed> $config): void

Constructor hook method.

Implement this method to avoid having to overwrite the constructor and call parent.

Parameters

array<string, mixed> $config: The configuration settings provided to this helper.

Returns

void

last() ¶ public

last(string|int $last = 'last >>', array<string, mixed> $options = []): string

Returns a last or set of numbers for the last pages.

echo $this->Paginator->last('last >');

Creates a single link for the last page. Will output nothing if you are on the last page.

echo $this->Paginator->last(3);

Will create links for the last 3 pages. Once you enter the page range, no output will be created.

Options:

escape Whether to HTML escape the text.
url An array of additional URL options to use for link generation.

Parameters

string|int $last optional: if string use as label for the link, if numeric print page numbers
array<string, mixed> $options optional: Array of options

Returns

string

Links

https://book.cakephp.org/5/en/views/helpers/paginator.html#creating-jump-links

limitControl() ¶ public

limitControl(array<string, string> $limits = [], int|null $default = null, array<string, mixed> $options = []): string

Dropdown select for pagination limit. This will generate a wrapping form.

Parameters

array<string, string> $limits optional: The options array.
int|null $default optional: Default option for pagination limit. Defaults to $this->param('perPage').
array<string, mixed> $options optional: Options for Select tag attributes like class, id or event

Returns

string

meta() ¶ public

meta(array<string, mixed> $options = []): string|null

Returns the meta-links for a paginated result set.

echo $this->Paginator->meta();

Echos the links directly, will output nothing if there is neither a previous nor next page.

$this->Paginator->meta(['block' => true]);

Will append the output of the meta function to the named block - if true is passed the "meta" block is used.

Options:

block The block name to append the output to, or false/absent to return as a string
prev (default True) True to generate meta for previous page
next (default True) True to generate meta for next page
first (default False) True to generate meta for first page
last (default False) True to generate meta for last page

Parameters

array<string, mixed> $options optional: Array of options

Returns

string|null

next() ¶ public

next(string $title = 'Next >>', array<string, mixed> $options = []): string

Generates a "next" link for a set of paged records

Options:

disabledTitle The text to used when the link is disabled. This defaults to the same text at the active link. Setting to false will cause this method to return ''.
escape Whether you want the contents html entity encoded, defaults to true
url An array of additional URL options to use for link generation.
templates An array of templates, or template file name containing the templates you'd like to use when generating the link for next page. The helper's original templates will be restored once next() is done.

Parameters

string $title optional: Title for the link. Defaults to 'Next >>'.
array<string, mixed> $options optional: Options for pagination link. See above for list of keys.

Returns

string

Links

https://book.cakephp.org/5/en/views/helpers/paginator.html#creating-jump-links

numbers() ¶ public

numbers(array<string, mixed> $options = []): string

Returns a set of numbers for the paged result set uses a modulus to decide how many numbers to show on each side of the current page (default: 8).

$this->Paginator->numbers(['first' => 2, 'last' => 2]);

Using the first and last options you can create links to the beginning and end of the page set.

Options

before Content to be inserted before the numbers, but after the first links.
after Content to be inserted after the numbers, but before the last links.
modulus How many numbers to include on either side of the current page, defaults to 8. Set to false to disable and to show all numbers.
first Whether you want first links generated, set to an integer to define the number of 'first' links to generate. If a string is set a link to the first page will be generated with the value as the title.
last Whether you want last links generated, set to an integer to define the number of 'last' links to generate. If a string is set a link to the last page will be generated with the value as the title.
templates An array of templates, or template file name containing the templates you'd like to use when generating the numbers. The helper's original templates will be restored once numbers() is done.
url An array of additional URL options to use for link generation.

The generated number links will include the 'ellipsis' template when the first and last options and the number of pages exceed the modulus. For example if you have 25 pages, and use the first/last options and a modulus of 8, ellipsis content will be inserted after the first and last link sets.

Parameters

array<string, mixed> $options optional: Options for the numbers.

Returns

string

Links

https://book.cakephp.org/5/en/views/helpers/paginator.html#creating-page-number-links

options() ¶ public

options(array<string, mixed> $options = []): void

Sets default options for all pagination links

Parameters

array<string, mixed> $options optional: Default options for pagination links. See PaginatorHelper::$options for list of keys.

Returns

void

paginated() ¶ protected

paginated(): Cake\Datasource\Paging\PaginatedInterface

Get pagination instance.

Returns

Cake\Datasource\Paging\PaginatedInterface

param() ¶ public

param(string $key): mixed

Convenience access to any of the paginator params.

Parameters

string $key: Key of the paginator params array to retrieve.

Returns

mixed

params() ¶ public

params(): array

Gets the current paging parameters from the resultset for the given model

Returns

array

prev() ¶ public

prev(string $title = '<< Previous', array<string, mixed> $options = []): string

Generates a "previous" link for a set of paged records

Options:

disabledTitle The text to used when the link is disabled. This defaults to the same text at the active link. Setting to false will cause this method to return ''.
escape Whether you want the contents html entity encoded, defaults to true
url An array of additional URL options to use for link generation.
templates An array of templates, or template file name containing the templates you'd like to use when generating the link for previous page. The helper's original templates will be restored once prev() is done.

Parameters

string $title optional: Title for the link. Defaults to '<< Previous'.
array<string, mixed> $options optional: Options for pagination link. See above for list of keys.

Returns

string

Links

https://book.cakephp.org/5/en/views/helpers/paginator.html#creating-jump-links

setConfig() ¶ public

setConfig(array<string, mixed>|string $key, mixed|null $value = null, bool $merge = true): $this

Sets the config.

Usage

Setting a specific value:

$this->setConfig('key', $value);

Setting a nested value:

$this->setConfig('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->setConfig(['one' => 'value', 'another' => 'value']);

Parameters

array<string, mixed>|string $key: The key to set, or a complete array of configs.
mixed|null $value optional: The value to set.
bool $merge optional: Whether to recursively merge or overwrite existing config, defaults to true.

Returns

$this

Throws

Cake\Core\Exception\CakeException
When trying to set a key that is invalid.

setPaginated() ¶ public

setPaginated(Cake\Datasource\Paging\PaginatedInterface $paginated, array<string, mixed> $options = []): void

Set paginated results.

Parameters

Cake\Datasource\Paging\PaginatedInterface $paginated: Instance to use.
array<string, mixed> $options optional: Options array.

Returns

void

setTemplates() ¶ public

setTemplates(array<string, string> $templates): $this

Sets templates to use.

Parameters

array<string, string> $templates: Templates to be added.

Returns

$this

sort() ¶ public

sort(string $key, array<string, mixed>|string|null $title = null, array<string, mixed> $options = []): string

Generates a sorting link. Sets named parameters for the sort and direction. Handles direction switching automatically.

Options:

escape Whether you want the contents html entity encoded, defaults to true.
direction The default direction to use when this link isn't active.
lock Lock direction. Will only use the default direction then, defaults to false.

Parameters

string $key: The name of the key that the recordset should be sorted.
array<string, mixed>|string|null $title optional: Title for the link. If $title is null $key will be used for the title and will be generated by inflection. It can also be an array with keys asc and desc for specifying separate titles based on the direction.
array<string, mixed> $options optional: Options for sorting link. See above for list of keys.

Returns

string

Links

https://book.cakephp.org/5/en/views/helpers/paginator.html#creating-sort-links

sortDir() ¶ protected

sortDir(): string

Gets the current direction the recordset is sorted

Returns

string

templater() ¶ public

templater(): Cake\View\StringTemplate

Returns the templater instance.

Returns

Cake\View\StringTemplate

total() ¶ public

total(): int|null

Gets the total number of pages in the recordset for the given model.

Returns

int|null

Property Detail

`$Form` ¶ public @property

Type

Cake\View\Helper\FormHelper

`$Html` ¶ public @property

Type

Cake\View\Helper\HtmlHelper

`$Number` ¶ public @property

Type

Cake\View\Helper\NumberHelper

`$Url` ¶ public @property

Type

Cake\View\Helper\UrlHelper

`$_View` ¶ protected

The View instance this helper is attached to

Type

Cake\View\View

`$_config` ¶ protected

Runtime config

Type

array<string, mixed>

`$_configInitialized` ¶ protected

Whether the config property has already been configured with defaults

Type

bool

`$_defaultConfig` ¶ protected

Default config for this class

Options: Holds the default options for pagination links

The values that may be specified are:

url Url of the action. See Router::url()
url['?']['sort'] the key that the recordset is sorted.
url['?']['direction'] Direction of the sorting (default: 'asc').
url['?']['page'] Page number to use in links.
escape Defines if the title field for the link should be escaped (default: true).
routePlaceholders An array specifying which paging params should be passed as route placeholders instead of query string parameters. The array can have values 'sort', 'direction', 'page'.

Templates: the templates used by this class

Type

array<string, mixed>

`$_templater` ¶ protected

StringTemplate instance.

Type

Cake\View\StringTemplate|null

`$helperInstances` ¶ protected

Loaded helper instances.

Type

array<string,Cake\View\Helper>

`$helpers` ¶ protected

List of helpers used by this helper

Type

array

`$paginated` ¶ protected

Paginated results

Type

Cake\Datasource\Paging\PaginatedInterface

Namespaces

Class PaginatorHelper

Property Summary

Method Summary

__construct() public

__debugInfo() public

__get() public

_configDelete() protected

_configRead() protected

_configWrite() protected

_confirm() protected

_firstNumber() protected

_formatNumber() protected

_getNumbersStartAndEnd() protected

_lastNumber() protected

_modulusNumbers() protected

_numbers() protected

_removeAlias() protected

_toggledLink() protected

addClass() public

configShallow() public

counter() public

current() public

first() public

formatTemplate() public

generateUrl() public

generateUrlParams() public

getConfig() public

getConfigOrFail() public

getTemplates() public

getView() public

hasNext() public

hasPage() public

hasPrev() public

implementedEvents() public

initialize() public

last() public

limitControl() public

meta() public

next() public

numbers() public

options() public

paginated() protected

param() public

params() public

prev() public

setConfig() public

setPaginated() public

setTemplates() public

sort() public

sortDir() protected

templater() public

total() public

Method Detail

__construct() ¶ public

Parameters

__debugInfo() ¶ public

Returns

__get() ¶ public

Parameters

Returns

_configDelete() ¶ protected

Parameters

Returns

Throws

_configRead() ¶ protected

Parameters

Returns

_configWrite() ¶ protected

Parameters

Returns

Throws

_confirm() ¶ protected

Parameters

Returns

_firstNumber() ¶ protected

Parameters

Returns

_formatNumber() ¶ protected

Parameters