Class
PaginatorComponent

This component is used to handle automatic model data pagination. The primary way to use this component is to call the paginate() method. There is a convenience wrapper on Controller as well.

Configuring pagination

You configure pagination when calling paginate(). See that method for more details.

Namespace: Cake\Controller\Component
Deprecated: 4.4.0 Use Cake\Datasource\Paging\Paginator directly.
Link: https://book.cakephp.org/4/en/controllers/components/pagination.html

Property Summary

$_componentMap protected

array<string, array>

A component lookup table used to lazy load component objects.
$_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
$_paginator protected

Cake\Datasource\Paging\NumericPaginator

Datasource paginator instance.
$_registry protected

Cake\Controller\ComponentRegistry

Component registry class used to lazy load components.
$components protected

array

Other Components this component uses.

Method Summary

__call() public

Proxy method calls to Paginator.
__construct() public

Constructor
__debugInfo() public

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

Magic method for lazy loading $components.
_configDelete() protected

Deletes a single config key.
_configRead() protected

Reads a config key.
_configWrite() protected

Writes a config key.
_setPagingParams() protected

Set paging params to request instance.
configShallow() public

Proxy setting config options to Paginator.
getConfig() public

Proxy getting config options to Paginator.
getConfigOrFail() public

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

Get the controller this component is bound to.
getPaginator() public

Get paginator instance.
implementedEvents() public

Events supported by this component.
initialize() public

Constructor hook method.
log() public

Convenience method to write a message to Log. See Log::write() for more information on writing to logs.
mergeOptions() public

Merges the various options that Pagination uses. Pulls settings together from the following places:
paginate() public

Handles automatic pagination of model records.
setConfig() public

Proxy setting config options to Paginator.
setPaginator() public

Set paginator instance.

Method Detail

__call() ¶ public

__call(string $method, array $args): mixed

Proxy method calls to Paginator.

Parameters

string $method: Method name.
array $args: Method arguments.

Returns

mixed

__construct() ¶ public

__construct(Cake\Controller\ComponentRegistry $registry, array<string, mixed> $config = [])

Constructor

Parameters

Cake\Controller\ComponentRegistry $registry
array<string, mixed> $config optional

__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\Controller\Component|null

Magic method for lazy loading $components.

Parameters

string $name: Name of component to get.

Returns

Cake\Controller\Component|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

_setPagingParams() ¶ protected

_setPagingParams(): void

Set paging params to request instance.

Returns

void

configShallow() ¶ public

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

Proxy setting config options to Paginator.

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

getConfig() ¶ public

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

Proxy getting config options to Paginator.

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

getController() ¶ public

getController(): Cake\Controller\Controller

Get the controller this component is bound to.

Returns

Cake\Controller\Controller

getPaginator() ¶ public

getPaginator(): Cake\Datasource\Paging\NumericPaginator

Get paginator instance.

Returns

Cake\Datasource\Paging\NumericPaginator

implementedEvents() ¶ public

implementedEvents(): array<string, mixed>

Events supported by this component.

Uses Conventions to map controller events to standard component callback method names. By defining one of the callback methods a component 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 components 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 component.

Returns

void

log() ¶ public

log(string $message, string|int $level = LogLevel::ERROR, array|string $context = []): bool

Convenience method to write a message to Log. See Log::write() for more information on writing to logs.

Parameters

string $message: Log message.
string|int $level optional: Error level.
array|string $context optional: Additional log data relevant to this message.

Returns

bool

mergeOptions() ¶ public

mergeOptions(string $alias, array<string, mixed> $settings): array<string, mixed>

Merges the various options that Pagination uses. Pulls settings together from the following places:

General pagination settings
Model specific settings.
Request parameters

The result of this method is the aggregate of all the option sets combined together. You can change config value allowedParameters to modify which options/values can be set using request parameters.

Parameters

string $alias: Model alias being paginated, if the general settings has a key with this value that key's settings will be used for pagination instead of the general ones.
array<string, mixed> $settings: The settings to merge with the request data.

Returns

array<string, mixed>

paginate() ¶ public

paginate(Cake\Datasource\RepositoryInterfaceCake\Datasource\QueryInterface $object, array<string, mixed> $settings = []): Cake\Datasource\ResultSetInterface

Handles automatic pagination of model records.

Configuring pagination

When calling paginate() you can use the $settings parameter to pass in pagination settings. These settings are used to build the queries made and control other pagination settings.

If your settings contain a key with the current table's alias. The data inside that key will be used. Otherwise, the top level configuration will be used.

 $settings = [
   'limit' => 20,
   'maxLimit' => 100
 ];
 $results = $paginator->paginate($table, $settings);

The above settings will be used to paginate any Table. You can configure Table specific settings by keying the settings with the Table alias.

 $settings = [
   'Articles' => [
     'limit' => 20,
     'maxLimit' => 100
   ],
   'Comments' => [ ... ]
 ];
 $results = $paginator->paginate($table, $settings);

This would allow you to have different pagination settings for Articles and Comments tables.

Controlling sort fields

By default CakePHP will automatically allow sorting on any column on the table object being paginated. Often times you will want to allow sorting on either associated columns or calculated fields. In these cases you will need to define an allowed list of fields you wish to allow sorting on. You can define the allowed fields in the $settings parameter:

$settings = [
  'Articles' => [
    'finder' => 'custom',
    'sortableFields' => ['title', 'author_id', 'comment_count'],
  ]
];

Passing an empty array as allowed list disallows sorting altogether.

Paginating with custom finders

You can paginate with any find type defined on your table using the finder option.

 $settings = [
   'Articles' => [
     'finder' => 'popular'
   ]
 ];
 $results = $paginator->paginate($table, $settings);

Would paginate using the find('popular') method.

You can also pass an already created instance of a query to this method:

$query = $this->Articles->find('popular')->matching('Tags', function ($q) {
  return $q->where(['name' => 'CakePHP'])
});
$results = $paginator->paginate($query);

Scoping Request parameters

By using request parameter scopes you can paginate multiple queries in the same controller action:

$articles = $paginator->paginate($articlesQuery, ['scope' => 'articles']);
$tags = $paginator->paginate($tagsQuery, ['scope' => 'tags']);

Each of the above queries will use different query string parameter sets for pagination data. An example URL paginating both results would be:

/dashboard?articles[page]=1&tags[page]=2

Parameters

Cake\Datasource\RepositoryInterfaceCake\Datasource\QueryInterface $object: Table or query to paginate.
array<string, mixed> $settings optional: The settings/configuration used for pagination.

Returns

Cake\Datasource\ResultSetInterface

Throws

Cake\Http\Exception\NotFoundException

setConfig() ¶ public

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

Proxy setting config options to Paginator.

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

setPaginator() ¶ public

setPaginator(Cake\Datasource\Paging\NumericPaginator $paginator): $this

Set paginator instance.

Parameters

Cake\Datasource\Paging\NumericPaginator $paginator: Paginator instance.

Returns

$this

Property Detail

`$_componentMap` ¶ protected

A component lookup table used to lazy load component objects.

Type

array<string, array>

`$_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

These are merged with user-provided config when the component is used.

Type

array<string, mixed>

`$_paginator` ¶ protected

Datasource paginator instance.

Type

Cake\Datasource\Paging\NumericPaginator

`$_registry` ¶ protected

Component registry class used to lazy load components.

Type

Cake\Controller\ComponentRegistry

`$components` ¶ protected

Other Components this component uses.

Type

array

Namespaces

Class PaginatorComponent

Configuring pagination

Property Summary

Method Summary

__call() public

__construct() public

__debugInfo() public

__get() public

_configDelete() protected

_configRead() protected

_configWrite() protected

_setPagingParams() protected

configShallow() public

getConfig() public

getConfigOrFail() public

getController() public

getPaginator() public

implementedEvents() public

initialize() public

log() public

mergeOptions() public

paginate() public

setConfig() public

setPaginator() public

Method Detail

__call() ¶ public

Parameters

Returns

__construct() ¶ public

Parameters

__debugInfo() ¶ public

Returns

__get() ¶ public

Parameters

Returns

_configDelete() ¶ protected

Parameters

Returns

Throws

_configRead() ¶ protected

Parameters

Returns

_configWrite() ¶ protected

Parameters

Returns

Throws

_setPagingParams() ¶ protected

Returns

configShallow() ¶ public

Parameters

Returns

getConfig() ¶ public

Usage

Parameters

Returns

getConfigOrFail() ¶ public

Parameters

Returns

Throws

getController() ¶ public

Returns

getPaginator() ¶ public

Returns

implementedEvents() ¶ public

Returns

initialize() ¶ public

Parameters

Returns

log() ¶ public

Parameters

Returns

mergeOptions() ¶ public

Parameters

Returns

paginate() ¶ public

Configuring pagination

Controlling sort fields

Paginating with custom finders

Scoping Request parameters

Class
PaginatorComponent

`$_componentMap` ¶ protected

`$_config` ¶ protected

`$_configInitialized` ¶ protected

`$_defaultConfig` ¶ protected

`$_paginator` ¶ protected

`$_registry` ¶ protected

`$components` ¶ protected