Fr3nch13/CakePHP Utilities

PaginatorComponent extends Component
in package

Application

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.

Use Cake\Datasource\Paging\Paginator directly.

Configuring pagination

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

Properties

$_componentMap : array<string, array<string|int, mixed>>: A component lookup table used to lazy load component objects.
$_config : array<string, mixed>: Runtime config
$_configInitialized : bool: Whether the config property has already been configured with defaults
$_defaultConfig : array<string, mixed>: Default config
$_paginator : NumericPaginator: Datasource paginator instance.
$_registry : ComponentRegistry: Component registry class used to lazy load components.
$components : array<string|int, mixed>: Other Components this component uses.

Methods

__call() : mixed: Proxy method calls to Paginator.
__construct() : mixed: Constructor
__debugInfo() : array<string, mixed>: Returns an array that can be used to describe the internal state of this object.
__get() : Component|null: Magic method for lazy loading $components.
configShallow() : $this: Proxy setting config options to Paginator.
getConfig() : mixed: Proxy getting config options to Paginator.
getConfigOrFail() : mixed: Returns the config for this specific key.
getController() : Controller: Get the controller this component is bound to.
getPaginator() : NumericPaginator: Get paginator instance.
implementedEvents() : array<string, mixed>: Events supported by this component.
initialize() : void: Constructor hook method.
log() : bool: Convenience method to write a message to Log. See Log::write() for more information on writing to logs.
mergeOptions() : array<string, mixed>: Merges the various options that Pagination uses.
paginate() : ResultSetInterface: Handles automatic pagination of model records.
setConfig() : $this: Proxy setting config options to Paginator.
setPaginator() : $this: Set paginator instance.
_configDelete() : void: Deletes a single config key.
_configRead() : mixed: Reads a config key.
_configWrite() : void: Writes a config key.
_setPagingParams() : void: Set paging params to request instance.

$_componentMap

A component lookup table used to lazy load component objects.


    protected
        array<string, array<string|int, mixed>>
    $_componentMap
     = []

$_config

Runtime config


    protected
        array<string, mixed>
    $_config
     = []

$_configInitialized

Whether the config property has already been configured with defaults


    protected
        bool
    $_configInitialized
     = false

$_defaultConfig

Default config


    protected
        array<string, mixed>
    $_defaultConfig
     = []

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

$_paginator

Datasource paginator instance.


    protected
        NumericPaginator
    $_paginator

$_registry

Component registry class used to lazy load components.


    protected
        ComponentRegistry
    $_registry

$components

Other Components this component uses.


    protected
        array<string|int, mixed>
    $components
     = []

__call()

Proxy method calls to Paginator.


    public
                    __call(string $method, array<string|int, mixed> $args) : mixed

Parameters

$method : string: Method name.
$args : array<string|int, mixed>: Method arguments.

__construct()

Constructor


    public
                    __construct(ComponentRegistry $registry[, array<string|int, mixed> $config = [] ]) : mixed

Parameters

$registry : ComponentRegistry: A component registry this component can use to lazy load its components.
$config : array<string|int, mixed> = []: Array of configuration settings.

__debugInfo()

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


    public
                    __debugInfo() : array<string, mixed>

Return values

array<string, mixed>

__get()

Magic method for lazy loading $components.


    public
                    __get(string $name) : Component|null

Parameters

$name : string: Name of component to get.

Return values

Component|null —

A Component object or null.

configShallow()

Proxy setting config options to Paginator.


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

Parameters

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

Return values

$this

getConfig()

Proxy getting config options to Paginator.


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

Parameters

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

Return values

mixed —

Config value being read.

getConfigOrFail()

Returns the config for this specific key.


    public
                    getConfigOrFail(string $key) : mixed

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

Parameters

$key : string: The key to get.

Return values

mixed —

Configuration data at the named key

getController()

Get the controller this component is bound to.


    public
                    getController() : Controller

Return values

Controller —

The bound controller.

getPaginator()

Get paginator instance.


    public
                    getPaginator() : NumericPaginator

Return values

NumericPaginator

implementedEvents()

Events supported by this component.


    public
                    implementedEvents() : array<string, mixed>

Return values

array<string, mixed>

initialize()

Constructor hook method.


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

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

Parameters

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

log()

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


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

Parameters

$message : string: Log message.
$level : string|int = LogLevel::ERROR: Error level.
$context : array<string|int, mixed>|string = []: Additional log data relevant to this message.

Return values

bool —

Success of log write.

mergeOptions()

Merges the various options that Pagination uses.


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

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

$alias : string: 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.
$settings : array<string, mixed>: The settings to merge with the request data.

Return values

array<string, mixed> —

Array of merged options.

paginate()

Handles automatic pagination of model records.


    public
                    paginate(RepositoryInterface|QueryInterface $object[, array<string, mixed> $settings = [] ]) : ResultSetInterface

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

$object : RepositoryInterface|QueryInterface: Table or query to paginate.
$settings : array<string, mixed> = []: The settings/configuration used for pagination.

Return values

ResultSetInterface —

Query results

setConfig()

Proxy setting config options to Paginator.


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

Parameters

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

Return values

$this

setPaginator()

Set paginator instance.


    public
                    setPaginator(NumericPaginator $paginator) : $this

Parameters

$paginator : NumericPaginator: Paginator instance.

Return values

$this

_configDelete()

Deletes a single config key.


    protected
                    _configDelete(string $key) : void

Parameters

$key : string: Key to delete.

_configRead()

Reads a config key.


    protected
                    _configRead(string|null $key) : mixed

Parameters

$key : string|null: Key to read.

_configWrite()

Writes a config key.


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

Parameters

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

_setPagingParams()

Set paging params to request instance.


    protected
                    _setPagingParams() : void

PaginatorComponent extends Component in package Application

Configuring pagination

Tags

Table of Contents

Properties

Methods

Properties

$_componentMap

$_config

$_configInitialized

$_defaultConfig

$_paginator

$_registry

$components

Methods

__call()

Parameters

__construct()

Parameters

Tags

__debugInfo()

Return values

__get()

Parameters

Return values

configShallow()

Parameters

Return values

getConfig()

Parameters

Return values

getConfigOrFail()

Parameters

Tags

Return values

getController()

Return values

getPaginator()

Return values

implementedEvents()

Return values

initialize()

Parameters

log()

Parameters

Return values

mergeOptions()

Parameters

Return values

paginate()

Configuring pagination

Controlling sort fields

Paginating with custom finders

Scoping Request parameters

Parameters

Tags

Return values

setConfig()

Parameters

Return values

setPaginator()

Parameters

Return values

_configDelete()

Parameters

Tags

_configRead()

Parameters

_configWrite()

Parameters

Tags

_setPagingParams()

PaginatorComponent extends Component
in package

Application