Spec-Zone.ru › CakePHP 4.3

Класс SimplePaginator

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

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

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

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

  • $_config protected
    array<string, mixed>

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

  • $_configInitialized protected
    bool

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

  • $_defaultConfig protected
    array<string, mixed>

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

  • $_pagingParams protected
    array

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

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

  • _configDelete() protected

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

  • _configRead() protected

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

  • _configWrite() protected

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

  • _extractFinder() protected

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

  • _prefix() protected

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

  • _removeAliases() protected

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

  • addPageCountParams() protected

    Добавляет параметры «страница» и «количество страниц».

  • addPrevNextParams() protected

    Добавляет параметры «предыдущая страница» и «следующая страница».

  • addSortingParams() protected

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

  • addStartEndParams() protected

    Добавляет параметры «начало» и «конец».

  • buildParams() protected

    Создаёт параметры пагинации.

  • checkLimit() public

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

  • configShallow() public

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

  • extractData() protected

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

  • getAllowedParameters() protected

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

  • getConfig() public

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

  • getConfigOrFail() public

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

  • getCount() protected

    Простой пагинатор не выполняет запрос подсчёта, поэтому этот метод возвращает null.

  • getDefaults() public

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

  • getPagingParams() public

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

  • getQuery() protected

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

  • getSortableFields() protected

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

  • mergeOptions() public

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

  • paginate() public

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

  • setConfig() public

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

  • validateSort() public

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

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

_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(array<string, mixed>|string $key, mixed $value, string|bool $merge = false): void

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

Параметры

array<string, mixed>|string $key

Ключ для записи.

mixed $value

Значение для записи.

string|bool $merge optional

True для рекурсивного слияния, 'shallow' для простого слияния, false для перезаписи, по умолчанию false.

Возвращает

void

Выбрасывает

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

_extractFinder() protected 

_extractFinder(array<string, mixed> $options): array

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

Параметры

array<string, mixed> $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<string, mixed> $fields, string $model): array<string, mixed>

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

Параметры

array<string, mixed> $fields

Текущие поля.

string $model

Текущий алиас модели.

Возвращает

array<string, mixed>

addPageCountParams() protected 

addPageCountParams(array<string, mixed> $params, array $data): array<string, mixed>

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

Параметры

array<string, mixed> $params

Параметры пагинации.

array $data

Данные пагинатора.

Возвращает

array<string, mixed>

addPrevNextParams() protected 

addPrevNextParams(array<string, mixed> $params, array $data): array<string, mixed>

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

Параметры

array<string, mixed> $params

Параметры пагинатора.

array $data

Данные пагинации.

Возвращает

array<string, mixed>

addSortingParams() protected 

addSortingParams(array<string, mixed> $params, array $data): array<string, mixed>

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

Параметры

array<string, mixed> $params

Параметры пагинатора.

array $data

Данные пагинации.

Возвращает

array<string, mixed>

addStartEndParams() protected 

addStartEndParams(array<string, mixed> $params, array $data): array<string, mixed>

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

Параметры

array<string, mixed> $params

Параметры пагинации.

array $data

Данные пагинатора.

Возвращает

array<string, mixed>

buildParams() protected 

buildParams(array<string, mixed> $data): array<string, mixed>

Создаёт параметры пагинации.

Параметры

array<string, mixed> $data

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

Возвращает

array<string, mixed>

checkLimit() public 

checkLimit(array<string, mixed> $options): array<string, mixed>

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

Параметры

array<string, mixed> $options

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

Возвращает

array<string, mixed>

configShallow() public 

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

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

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

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

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

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

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

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

Параметры

array<string, mixed>|string $key

Ключ для установки или массив всей конфигурации.

mixed|null $value optional

Значение для установки.

Возвращает

$this

extractData() protected 

extractData(Cake\Datasource\RepositoryInterface $object, array<string, mixed> $params, array<string, mixed> $settings): array

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

Параметры

Cake\Datasource\RepositoryInterface $object

Объект репозитория.

array<string, mixed> $params

Параметры запроса.

array<string, mixed> $settings

Настройки/конфигурация, используемые для пагинации.

Возвращает

array

getAllowedParameters() protected 

getAllowedParameters(): array<string>

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

Возвращает

array<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

Простой пагинатор не выполняет запрос подсчёта, поэтому этот метод возвращает null.

Параметры

Cake\Datasource\QueryInterface $query

Экземпляр запроса.

array $data

Данные пагинации.

Возвращает

int|null

getDefaults() public 

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

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

Параметры

string $alias

Имя модели для получения настроек.

array<string, mixed> $settings

Настройки, используемые для объединения.

Возвращает

array<string, mixed>

getPagingParams() public 

getPagingParams(): array

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

Возвращает

array

getQuery() protected 

getQuery(Cake\Datasource\RepositoryInterface $object, Cake\Datasource\QueryInterface|null $query, array<string, mixed> $data): Cake\Datasource\QueryInterface

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

Параметры

Cake\Datasource\RepositoryInterface $object

Экземпляр хранилища.

Cake\Datasource\QueryInterface|null $query

Экземпляр запроса.

array<string, mixed> $data

Данные постраничной навигации.

Возвращает

Cake\Datasource\QueryInterface

getSortableFields() protected 

getSortableFields(array<string, mixed> $config): array<string>|null

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

Параметры

array<string, mixed> $config

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

Возвращает

array<string>|null

mergeOptions() public 

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

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

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

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

Параметры

array<string, mixed> $params

Параметры запроса.

array $settings

Настройки для слияния с данными запроса.

Возвращает

array<string, mixed>

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(array<string, mixed>|string $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']);

Параметры

array<string, mixed>|string $key

Ключ для установки или весь массив конфигураций.

mixed|null $value optional

Значение для установки.

bool $merge optional

Выполнять рекурсивное слияние или перезаписывать существующую конфигурацию, по умолчанию true.

Возвращает

$this

Выбрасывает

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

validateSort() public 

validateSort(Cake\Datasource\RepositoryInterface $object, array<string, mixed> $options): array<string, mixed>

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

Можно сортировать только по полям или виртуальным полям. Параметр direction также будет отфильтрован. Кроме того, ключи sort + direction будут преобразованы в дружественный модели ключ order.

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

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

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

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

Параметры

Cake\Datasource\RepositoryInterface $object

Объект хранилища.

array<string, mixed> $options

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

Возвращает

array<string, mixed>

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

$_config protected

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

Тип

array<string, mixed>

$_configInitialized protected

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

Тип

bool

$_defaultConfig protected

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

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

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

Тип

array<string, mixed>

$_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.3/class-Cake.Datasource.SimplePaginator.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API