Класс Paginator

Этот класс используется для обработки автоматической постраничной навигации данных модели.

Пространство имён: Cake\Datasource

Краткое описание свойств

$_config protected

array

Конфигурация выполнения
$_configInitialized protected

bool

Указывает, была ли конфигурация уже настроена по умолчанию
$_defaultConfig protected

array

Настройки постраничной навигации по умолчанию.
$_pagingParams protected

array

Параметры постраничной навигации после выполнения операции.

Краткое описание методов

_configDelete() protected

Удаляет один ключ конфигурации.
_configRead() protected

Читает ключ конфигурации.
_configWrite() protected

Записывает ключ конфигурации.
_extractFinder() protected

Извлекает имя и параметры поиска из предоставленных опций постраничной навигации.
_prefix() protected

Добавляет префикс к полю, если это возможно.
_removeAliases() protected

Удаляет псевдонимы при необходимости.
addPageCountParams() protected

Добавляет параметры "page" и "pageCount".
addPrevNextParams() protected

Добавляет параметры "prevPage" и "nextPage".
addSortingParams() protected

Добавляет параметры сортировки/упорядочивания.
addStartEndParams() protected

Добавляет параметры "start" и "end".
buildParams() protected

Создаёт параметры постраничной навигации.
checkLimit() public

Проверяет параметр ограничения и гарантирует, что он находится в пределах допустимых значений maxLimit.
configShallow() public

Объединяет предоставленную конфигурацию с существующей. В отличие от config(), которое выполняет рекурсивное объединение для вложенных ключей, этот метод выполняет простое объединение.
extractData() protected

Извлекает данные, необходимые для постраничной навигации.
getAllowedParameters() protected

Метод-обёртка для чтения устаревшего параметра whitelist или allowedParameters.
getConfig() public

Возвращает конфигурацию.
getConfigOrFail() public

Возвращает конфигурацию для данного ключа.
getCount() protected

Получает общее количество записей.
getDefaults() public

Получает настройки для $model. Если нет настроек для определённого хранилища, будут использоваться общие настройки.
getPagingParams() public

Получает параметры постраничной навигации после операции.
getQuery() protected

Получает запрос для получения результатов постраничной навигации.
getSortableFields() protected

Метод-обёртка для чтения устаревшего параметра sortWhitelist или sortableFields.
mergeOptions() public

Объединяет различные параметры, используемые Paginator. Собраны настройки из следующих источников:
paginate() public

Обрабатывает автоматическую постраничную навигацию записей модели.
setConfig() public

Устанавливает конфигурацию.
validateSort() public

Проверяет, что указанная сортировка может быть применена к $object.

END_OF_DOCUMENT_MARKER

Подробное описание методов

_configDelete() protected

_configDelete(string $key): void

Удаляет один ключ конфигурации.

Параметры

string $key: Ключ для удаления.

Возвращает

void

Исключения

Cake\Core\Exception\CakeException
если пытаетесь перезаписать существующую конфигурацию

_configRead() protected

_configRead(string|null $key): mixed

Считывает ключ конфигурации.

Параметры

string|null $key: Ключ для чтения.

Возвращает

mixed

_configWrite() protected

_configWrite(string|array $key, mixed $value, bool|string $merge = false): void

Записывает ключ конфигурации.

Параметры

string|array $key: Ключ для записи.
mixed $value: Значение для записи.
bool|string $merge optional: True для рекурсивного слияния, 'shallow' для простого слияния, false для перезаписи, по умолчанию false.

Возвращает

void

Исключения

Cake\Core\Exception\CakeException
если пытаетесь перезаписать существующую конфигурацию

_extractFinder() protected

_extractFinder(array $options): array

Извлекает имя и опции поиска из предоставленных опций пагинации.

Параметры

array $options: опции пагинации.

Возвращает

array

_prefix() protected

_prefix(Cake\Datasource\RepositoryInterface $object, array $order, bool $allowed = false): array

Добавляет префикс к полю, если возможно, используя псевдоним таблицы.

Параметры

Cake\Datasource\RepositoryInterface $object: Объект репозитория.
array $order: Массив порядка.
bool $allowed optional: Разрешено ли поле.

Возвращает

array

_removeAliases() protected

_removeAliases(array $fields, string $model): array

Удаляет псевдоним, если необходимо.

Параметры

array $fields: Текущие поля
string $model: Текущий псевдоним модели

Возвращает

array

addPageCountParams() protected

addPageCountParams(array $params, array $data): array

Добавляет параметры "page" и "pageCount".

Параметры

array $params: Параметры пагинации.
array $data: Данные пагинатора.

Возвращает

array

addPrevNextParams() protected

addPrevNextParams(array $params, array $data): array

Добавляет параметры "prevPage" и "nextPage".

Параметры

array $params: Параметры пагинатора.
array $data: Данные пагинации.

Возвращает

array

addSortingParams() protected

addSortingParams(array $params, array $data): array

Добавляет параметры сортировки.

Параметры

array $params: Параметры пагинатора.
array $data: Данные пагинации.

Возвращает

array

addStartEndParams() protected

addStartEndParams(array $params, array $data): array

Добавляет параметры "start" и "end".

Параметры

array $params: Параметры пагинации.
array $data: Данные пагинатора.

Возвращает

array

buildParams() protected

buildParams(array $data): array

Формирует параметры пагинации.

Параметры

array $data: Данные пагинатора, содержащие ключи 'options', 'count', 'defaults', 'finder', 'numResults'.

Возвращает

array

checkLimit() public

checkLimit(array $options): array

Проверяет параметр limit и гарантирует, что он находится в пределах границ maxLimit.

Параметры

array $options: Массив опций с ключом limit для проверки.

Возвращает

array

configShallow() public

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

Объединяет предоставленную конфигурацию с существующей конфигурацией. В отличие от config(), которая выполняет рекурсивное слияние для вложенных ключей, этот метод выполняет простое слияние.

Установка конкретного значения:

$this->configShallow('key', $value);

Установка вложенного значения:

$this->configShallow('some.nested.key', $value);

Обновление нескольких настроек конфигурации одновременно:

$this->configShallow(['one' => 'value', 'another' => 'value']);

Параметры

string|array $key: Ключ для установки или полный массив конфигураций.
mixed|null $value optional: Значение для установки.

Возвращает

$this

extractData() protected

extractData(Cake\Datasource\RepositoryInterface $object, array $params, array $settings): array

Извлекает необходимые данные пагинации.

Параметры

Cake\Datasource\RepositoryInterface $object: Объект репозитория.
array $params: Параметры запроса.
array $settings: Настройки/конфигурация, используемые для пагинации.

Возвращает

array

getAllowedParameters() protected

getAllowedParameters(): string[]

Метод-обёртка для чтения устаревшего параметра whitelist или allowedParameters.

Возвращает

string[]

getConfig() public

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

Возвращает конфигурацию.

Использование

Чтение всей конфигурации:

$this->getConfig();

Чтение определенного значения:

$this->getConfig('key');

Чтение вложенного значения:

$this->getConfig('some.nested.key');

Чтение со значением по умолчанию:

$this->getConfig('some-key', 'default-value');

Параметры

string|null $key optional: Ключ для получения или null для всей конфигурации.
mixed $default optional: Возвращаемое значение, когда ключ не существует.

Возвращает

mixed

getConfigOrFail() public

getConfigOrFail(string $key): mixed

Возвращает конфигурацию для данного ключа.

Значение конфигурации для данного ключа должно существовать, оно не может быть null.

Параметры

string $key: Ключ для получения.

Возвращает

mixed

Исключения

InvalidArgumentException

getCount() protected

getCount(Cake\Datasource\QueryInterface $query, array $data): int|null

Получает общее количество записей.

Параметры

Cake\Datasource\QueryInterface $query: Экземпляр запроса.
array $data: Данные пагинации.

Возвращает

int|null

getDefaults() public

getDefaults(string $alias, array $settings): array

Получить настройки для $model. Если для конкретного репозитория нет настроек, будут использованы общие настройки.

Параметры

string $alias: Имя модели для получения настроек.
array $settings: Настройки, используемые для объединения.

Возвращает

array

getPagingParams() public

getPagingParams(): array

Получить параметры постраничной навигации после операции постраничной обработки.

Возвращает

array

getQuery() protected

getQuery(Cake\Datasource\RepositoryInterface $object, Cake\Datasource\QueryInterface|null $query = null, array $data): Cake\Datasource\QueryInterface

Получить запрос для извлечения результатов постраничной навигации.

Параметры

Cake\Datasource\RepositoryInterface $object: Экземпляр репозитория.
Cake\Datasource\QueryInterface|null $query optional: Экземпляр запроса.
array $data: Данные для постраничной навигации.

Возвращает

Cake\Datasource\QueryInterface

getSortableFields() protected

getSortableFields(array $config): string[]|null

Метод-обёртка для чтения устаревшего параметра sortWhitelist или sortableFields.

Параметры

array $config: Данные конфигурации для объединения и вывода предупреждений.

Возвращает

string[]|null

mergeOptions() public

mergeOptions(array $params, array $settings): array

Объединяет различные параметры, используемые Paginator. Собирает настройки из следующих источников:

Общие настройки постраничной навигации
Настройки, специфичные для модели.
Параметры запроса

Результат этого метода — агрегированный набор всех объединённых наборов параметров. Вы можете изменить значение параметра allowedParameters для изменения параметров/значений, которые можно установить с помощью параметров запроса.

Параметры

array $params: Параметры запроса.
array $settings: Настройки для объединения с данными запроса.

Возвращает

array

paginate() public

paginate(Cake\Datasource\RepositoryInterfaceCake\Datasource\QueryInterface $object, array $params = [], array $settings = []): Cake\Datasource\ResultSetInterface

Обрабатывает автоматическую постраничную навигацию записей модели.

Настройка постраничной навигации

При вызове paginate() вы можете использовать параметр $settings для передачи настроек постраничной навигации. Эти настройки используются для построения запросов и управления другими настройками постраничной навигации.

Если ваши настройки содержат ключ с алиасом текущей таблицы, данные внутри этого ключа будут использованы. В противном случае будут использоваться настройки верхнего уровня.

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

Вышеуказанные настройки будут использоваться для постраничной навигации любого репозитория. Вы можете настроить настройки, специфичные для репозитория, присвоив настройки ключу с алиасом репозитория.

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

Это позволит вам иметь разные настройки постраничной навигации для репозиториев Articles и Comments.

Управление полями сортировки

По умолчанию CakePHP автоматически разрешает сортировку по любому столбцу объекта репозитория, по которому выполняется постраничная навигация. Зачастую вы хотите разрешить сортировку по связанным столбцам или вычисляемым полям. В таких случаях вам потребуется определить разрешённый список всех столбцов, по которым вы хотите разрешить сортировку. Вы можете определить разрешённые поля сортировки в параметре $settings.

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

Передача пустого массива в качестве sortableFields запрещает сортировку.

Постраничная навигация с помощью пользовательских находок

Вы можете выполнить постраничную навигацию с любым типом поиска, определённым в вашей таблице, используя опцию finder.

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

Выполнит постраничную навигацию с помощью метода find('popular').

Вы также можете передать уже созданный экземпляр запроса в этот метод:

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

Ограничение параметров запроса

Используя области параметров запроса, вы можете выполнить постраничную навигацию по нескольким запросам в одном действии контроллера:

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

Каждый из вышеуказанных запросов будет использовать разные наборы параметров строки запроса для данных постраничной навигации. Пример URL для постраничной навигации по обоим результатам:

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

Параметры

Cake\Datasource\RepositoryInterfaceCake\Datasource\QueryInterface $object: Репозиторий или запрос для постраничной навигации.
array $params optional: Параметры запроса
array $settings optional: Настройки/конфигурация, используемые для постраничной навигации.

Возвращает

Cake\Datasource\ResultSetInterface

Исключения

Cake\Datasource\Exception\PageOutOfBoundsException

setConfig() public

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

Устанавливает конфигурацию.

Использование

Установка определённого значения:

$this->setConfig('key', $value);

Установка вложенного значения:

$this->setConfig('some.nested.key', $value);

Обновление нескольких настроек конфигурации одновременно:

$this->setConfig(['one' => 'value', 'another' => 'value']);

Параметры

string|array $key: Ключ для установки или полный массив конфигураций.
mixed|null $value optional: Значение для установки.
bool $merge optional: Производить рекурсивное объединение или перезапись существующей конфигурации, по умолчанию true.

Возвращает

$this

Исключения

Cake\Core\Exception\CakeException
При попытке установить неверный ключ.

validateSort() public

validateSort(Cake\Datasource\RepositoryInterface $object, array $options): array

Проверка возможности выполнения желаемой сортировки по $object.

Разрешается сортировка только по полям или виртуальным полям. Параметр direction также будет очищен. В конечном итоге ключи sort и direction будут преобразованы в модель-дружественный ключ order.

Вы можете использовать опцию allowedParameters, чтобы контролировать, какие столбцы/поля доступны для сортировки через параметры URL. Это помогает предотвратить сортировку больших наборов результатов по неиндексированным значениям.

Если вам нужно сортировать по связанным столбцам или синтетическим свойствам, вам нужно использовать опцию sortableFields.

Любые столбцы, перечисленные в разрешённых полях сортировки, будут подразумеваемо надёжны. Вы можете использовать это для сортировки по синтетическим столбцам или столбцам, добавленным в пользовательских операциях поиска, которые могут отсутствовать в схеме.

Параметры сортировки по умолчанию, предоставленные paginate(), будут объединены с запрошенным пользователем полем/направлением сортировки.

Параметры

Cake\Datasource\RepositoryInterface $object: Объект репозитория.
array $options: Параметры постраничной навигации, используемые для этого запроса.

Возвращает

array

Подробное описание свойств

`$_config` protected

Конфигурация во время выполнения

Тип

array

`$_configInitialized` protected

Указание, была ли конфигурация уже настроена значениями по умолчанию

Тип

bool

`$_defaultConfig` protected

Настройки постраничной навигации по умолчанию.

При вызове paginate() эти настройки будут объединены с предоставленной вами конфигурацией.

maxLimit - Максимальный лимит, который пользователи могут выбрать для просмотра. По умолчанию 100
limit - Начальное количество элементов на странице. По умолчанию 20.
page - Начальная страница, по умолчанию 1.
allowedParameters - Список параметров, которые пользователи могут установить с помощью параметров запроса. Изменение этого списка позволит пользователям иметь больше влияния на постраничную навигацию, будьте внимательны с тем, что вы разрешаете.

Тип

array

`$_pagingParams` protected

Параметры постраничной навигации после выполнения операции постраничной навигации.

Тип

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.2/class-Cake.Datasource.Paginator.html