Class PaginatorHelper
Pagination Helper class for easy generation of pagination links.
PaginationHelper encloses all methods needed when working with pagination.
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
-
$_defaultModel protected
string|null
Default model of the paged sets
-
$_helperMap protected
array<string, array>
A helper lookup table used to lazy load helper objects.
-
$_templater protected
Cake\View\StringTemplate|null
StringTemplate instance.
-
$helpers protected
array
List of helpers used by this helper
Method Summary
-
__call() public
Provide non fatal errors on missing method calls.
-
__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.
-
_hasPage() protected
Does $model have $page in its range?
-
_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
-
defaultModel() public
Gets or sets the default model of the paged sets
-
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
-
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.
-
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() public
Gets the current direction the recordset is sorted
-
sortKey() public
Gets the current key by which 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
__call() ¶ public
__call(string $method, array $params): mixed|void
Provide non fatal errors on missing method calls.
Parameters
-
string
$method Method to invoke
-
array
$params Array of params for the method.
Returns
mixed|void
__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|void
Lazy loads helpers.
Parameters
-
string
$name Name of the property being accessed.
Returns
Cake\View\Helper|null|void
_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
_hasPage() ¶ protected
_hasPage(string|null $model, string $dir): bool
Does $model have $page in its range?
Parameters
-
string|null
$model Model name to get parameters for.
-
string
$dir Direction
Returns
bool
_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|null $model = null): string
Remove alias if needed.
Parameters
-
string
$field Current field
-
string|null
$model optional Current model alias
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', array<string, mixed> $options = []): string
Returns a counter string for the paged result set.
Options
model
The model to use, defaults to PaginatorHelper::defaultModel();
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.-
array<string, mixed>
$options optional Options for the counter string. See #options for list of keys. If string it will be used as format.
Returns
string
Links
current() ¶ public
current(string|null $model = null): int
Gets the current page of the recordset for the given model
Parameters
-
string|null
$model optional Optional model name. Uses the default if none is specified.
Returns
int
Links
defaultModel() ¶ public
defaultModel(string|null $model = null): string|null
Gets or sets the default model of the paged sets
Parameters
-
string|null
$model optional Model name to set
Returns
string|null
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:
model
The model to use defaults to PaginatorHelper::defaultModel()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
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 = [], string|null $model = null, 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.
-
string|null
$model optional Which model to paginate on
-
array
$url optional URL.
-
array<string, mixed>
$urlOptions optional Array of options
Returns
string
Links
generateUrlParams() ¶ public
generateUrlParams(array<string, mixed> $options = [], string|null $model = null, 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
-
string|null
$model optional Which model to paginate on
-
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(string|null $model = null): bool
Returns true if the given result set is not at the last page
Parameters
-
string|null
$model optional Optional model name. Uses the default if none is specified.
Returns
bool
Links
hasPage() ¶ public
hasPage(int $page = 1, string|null $model = null): 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.
-
string|null
$model optional Optional model name. Uses the default if none is specified.
Returns
bool
Throws
InvalidArgumentException
Links
hasPrev() ¶ public
hasPrev(string|null $model = null): bool
Returns true if the given result set is not at the first page
Parameters
-
string|null
$model optional Optional model name. Uses the default if none is specified.
Returns
bool
Links
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:
model
The model to use defaults to PaginatorHelper::defaultModel()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
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:
model
The model to use defaults to PaginatorHelper::defaultModel()block
The block name to append the output to, or false/absent to return as a stringprev
(default True) True to generate meta for previous pagenext
(default True) True to generate meta for next pagefirst
(default False) True to generate meta for first pagelast
(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 truemodel
The model to use, defaults to PaginatorHelper::defaultModel()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
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.model
Model to create numbers for, defaults to PaginatorHelper::defaultModel()modulus
How many numbers to include on either side of the current page, defaults to 8. Set tofalse
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
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
param() ¶ public
param(string $key, string|null $model = null): mixed
Convenience access to any of the paginator params.
Parameters
-
string
$key Key of the paginator params array to retrieve.
-
string|null
$model optional Optional model name. Uses the default if none is specified.
Returns
mixed
params() ¶ public
params(string|null $model = null): array
Gets the current paging parameters from the resultset for the given model
Parameters
-
string|null
$model optional Optional model name. Uses the default if none is specified.
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 truemodel
The model to use, defaults to PaginatorHelper::defaultModel()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
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.
setTemplates() ¶ public
setTemplates(array<string> $templates): $this
Sets templates to use.
Parameters
-
array<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.model
The model to use, defaults to PaginatorHelper::defaultModel().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
anddesc
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
sortDir() ¶ public
sortDir(string|null $model = null, array<string, mixed> $options = []): string
Gets the current direction the recordset is sorted
Parameters
-
string|null
$model optional Optional model name. Uses the default if none is specified.
-
array<string, mixed>
$options optional Options for pagination links.
Returns
string
Links
sortKey() ¶ public
sortKey(string|null $model = null, array<string, mixed> $options = []): string|null
Gets the current key by which the recordset is sorted
Parameters
-
string|null
$model optional Optional model name. Uses the default if none is specified.
-
array<string, mixed>
$options optional Options for pagination links.
Returns
string|null
Links
templater() ¶ public
templater(): Cake\View\StringTemplate
Returns the templater instance.
Returns
Cake\View\StringTemplate
total() ¶ public
total(string|null $model = null): int
Gets the total number of pages in the recordset for the given model.
Parameters
-
string|null
$model optional Optional model name. Uses the default if none is specified.
Returns
int
Property Detail
$_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.model
The name of the model.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>
$_helperMap ¶ protected
A helper lookup table used to lazy load helper objects.
Type
array<string, array>