CakePHP
  • Documentation
    • Book
    • API
    • Videos
    • Reporting Security Issues
    • Privacy Policy
    • Logos & Trademarks
  • Business Solutions
  • Swag
  • Road Trip
  • Team
  • Community
    • Community
    • Get Involved
    • Issues (Github)
    • Bakery
    • Featured Resources
    • Training
    • Meetups
    • My CakePHP
    • CakeFest
    • Newsletter
    • Linkedin
    • YouTube
    • Facebook
    • Twitter
    • Mastodon
    • Help & Support
    • Forum
    • Stack Overflow
    • IRC
    • Slack
    • Paid Support
CakePHP

C CakePHP 4.6 Strawberry API

  • Project:
    • CakePHP
      • CakePHP
      • Authentication
      • Authorization
      • Chronos
      • Elastic Search
      • Queue
  • Version:
    • 4.6
      • 5.2
      • 5.1
      • 5.0
      • 4.6
      • 4.5
      • 4.4
      • 4.3
      • 4.2
      • 4.1
      • 4.0
      • 3.10
      • 3.9
      • 3.8
      • 3.7
      • 3.6
      • 3.5
      • 3.4
      • 3.3
      • 3.2
      • 3.1
      • 3.0
      • 2.10
      • 2.9
      • 2.8
      • 2.7
      • 2.6
      • 2.5
      • 2.4
      • 2.3
      • 2.2
      • 2.1
      • 2.0
      • 1.3
      • 1.2

Namespaces

  • Global
  • Cake
    • Auth
    • Cache
    • Collection
    • Command
    • Console
    • Controller
      • Component
      • Exception
    • Core
    • Database
    • Datasource
    • Error
    • Event
    • Filesystem
    • Form
    • Http
    • I18n
    • Log
    • Mailer
    • Network
    • ORM
    • Routing
    • Shell
    • TestSuite
    • Utility
    • Validation
    • View

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\RepositoryInterface|Cake\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\RepositoryInterface|Cake\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
OpenHub
Pingping
Linode
  • Business Solutions
  • Showcase
  • Documentation
  • Book
  • API
  • Videos
  • Reporting Security Issues
  • Privacy Policy
  • Logos & Trademarks
  • Community
  • Get Involved
  • Issues (Github)
  • Bakery
  • Featured Resources
  • Training
  • Meetups
  • My CakePHP
  • CakeFest
  • Newsletter
  • Linkedin
  • YouTube
  • Facebook
  • Twitter
  • Mastodon
  • Help & Support
  • Forum
  • Stack Overflow
  • IRC
  • Slack
  • Paid Support

Generated using CakePHP API Docs