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

Properties summary

  • $_componentMap protected
    array

    A component lookup table used to lazy load component objects.

  • $_config protected
    array

    Runtime config

  • $_configInitialized protected
    bool

    Whether the config property has already been configured with defaults

  • $_defaultConfig protected
    array

    Default pagination settings.

  • $_paginator protected
    \Cake\Datasource\Paginator

    Datasource paginator instance.

  • $_registry protected
    \Cake\Controller\ComponentRegistry

    Component registry class used to lazy load components.

  • $components public
    array

    Other Components this component uses.

Method Summary

Method Detail

__call() public 

__call(string $method, array $args)

Proxy method calls to Paginator.

Parameters

string $method

Method name.

array $args

Method arguments.

Returns

mixed

__construct() public 

__construct(\Cake\Controller\ComponentRegistry $registry, array $config)

Constructor

Parameters

\Cake\Controller\ComponentRegistry $registry

A component registry this component can use to lazy load its components.

array $config optional

Array of configuration settings.

__debugInfo() public 

__debugInfo()

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

Returns

array

__get() public 

__get(string $name)

Magic method for lazy loading $components.

Parameters

string $name

Name of component to get.

Returns

\Cake\Controller\Component|null

A Component object or null.

_configDelete() protected 

_configDelete(string $key)

Deletes a single config key.

Parameters

string $key

Key to delete.

Throws

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

_configRead() protected 

_configRead(?string $key)

Reads a config key.

Parameters

string|null $key

Key to read.

Returns

mixed

_configWrite() protected 

_configWrite(mixed $key, mixed $value, mixed $merge)

Writes a config key.

Parameters

string|array $key

Key to write to.

mixed $value

Value to write.

bool|string $merge optional

True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.

Throws

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

_setPagingParams() protected 

_setPagingParams()

Set paging params to request instance.

configShallow() public 

configShallow(mixed $key, mixed $value)

Proxy setting config options to Paginator.

Parameters

string|array $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 $key, mixed $default)

Proxy getting config options to Paginator.

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

Config value being read.

getConfigOrFail() public 

getConfigOrFail(string $key)

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

Configuration data at the named key

Throws

InvalidArgumentException

getController() public 

getController()

Get the controller this component is bound to.

Returns

\Cake\Controller\Controller

The bound controller.

getPaginator() public 

getPaginator()

Get paginator instance.

Returns

\Cake\Datasource\Paginator

implementedEvents() public 

implementedEvents()

Events supported by this component.

Returns

array

initialize() public 

initialize(array $config)

Constructor hook method.

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

Parameters

array $config

The configuration settings provided to this component.

log() public 

log(string $message, mixed $level, mixed $context)

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

Parameters

string $message

Log message.

int|string $level optional

Error level.

string|array $context optional

Additional log data relevant to this message.

Returns

bool

Success of log write.

mergeOptions() public 

mergeOptions(string $alias, array $settings)

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 $settings

The settings to merge with the request data.

Returns

array

Array of merged options.

paginate() public 

paginate(object $object, array $settings)

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\RepositoryInterface|\Cake\Datasource\QueryInterface $object

Table or query to paginate.

array $settings optional

The settings/configuration used for pagination.

Returns

\Cake\Datasource\ResultSetInterface

Query results

Throws

Cake\Http\Exception\NotFoundException

setConfig() public 

setConfig(mixed $key, mixed $value, mixed $merge)

Proxy setting config options to Paginator.

Parameters

string|array $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\Paginator $paginator)

Set paginator instance.

Parameters

\Cake\Datasource\Paginator $paginator

Paginator instance.

Returns

$this

Property Detail

$_componentMap protected

A component lookup table used to lazy load component objects.

Type

array

$_config protected

Runtime config

Type

array

$_configInitialized protected

Whether the config property has already been configured with defaults

Type

bool

$_defaultConfig protected

Default pagination settings.

When calling paginate() these settings will be merged with the configuration you provide.

  • maxLimit - The maximum limit users can choose to view. Defaults to 100
  • limit - The initial number of items per page. Defaults to 20.
  • page - The starting page, defaults to 1.
  • allowedParameters - A list of parameters users are allowed to set using request parameters. Modifying this list will allow users to have more influence over pagination, be careful with what you permit.

Type

array

$_paginator protected

Datasource paginator instance.

Type

\Cake\Datasource\Paginator

$_registry protected

Component registry class used to lazy load components.

Type

\Cake\Controller\ComponentRegistry

$components public

Other Components this component uses.

Type

array

© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/4.1/class-Cake.Controller.Component.PaginatorComponent.html