Установка и настройка

Установка

bash

composer require myprogs/query-builder

Сервис-провайдер подключается автоматически. Пакету нужны PHP 8.3 или новее и Laravel 12 или 13.

Настройка

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

bash

php artisan vendor:publish --tag=query-builder-config

Файл — config/query-builder.php. Он также публикуется под тегом, который указан в документации spatie/laravel-query-builder, так что существующие скрипты продолжают работать:

bash

php artisan vendor:publish --tag=laravel-query-builder-config

Имена параметров

php

'parameters' => [
    'include' => 'include',
    'filter' => 'filter',
    'sort' => 'sort',
    'fields' => 'fields',
    'append' => 'append',
],

Имена параметров строки запроса. Измените их, если ваш API уже использует другие имена, например 'filter' => 'where' для ?where[name]=john.

Разделитель

php

'delimiter' => ',',
'filter_value_splitting_enabled' => true,

Разделитель параметров с несколькими значениями: filter[id]=1,2,3, sort=-created_at,name, include=posts,comments. Если filter_value_splitting_enabled равен false, значения фильтров не разбиваются и filter[name]=Smith, John — одно значение. У отдельного фильтра может быть свой разделитель, см. Фильтрация.

Суффиксы агрегатов

php

'suffixes' => [
    'count' => 'Count',
    'exists' => 'Exists',
    'min' => 'Min',
    'max' => 'Max',
    'sum' => 'Sum',
    'avg' => 'Avg',
],

Суффиксы, которые превращают имя связи в include агрегата: include=postsCount, include=postsExists. См. Подгрузка связей.

Неизвестные параметры

php

'disable_invalid_filter_query_exception' => false,
'disable_invalid_sort_query_exception' => false,
'disable_invalid_include_query_exception' => false,

По умолчанию фильтр, сортировка или include, которые эндпоинт не разрешает, выбрасывают исключение (ответ 400). Установите ключ в true, чтобы молча игнорировать такие параметры. Эти ключи действуют на spatie-совместимый API; definitions API всегда сообщает о неизвестных параметрах.

Имена полей

php

'convert_relation_names_to_snake_case_plural' => true,
'convert_relation_table_name_strategy' => null,
'convert_field_names_to_snake_case' => false,

Как сопоставляются ключи и имена в fields[...]:

convert_relation_names_to_snake_case_plural: ключ связи — её имя в snake case во множественном числе, include=userOwner&fields[user_owners]=id. При false — имя в том виде, как оно написано в include: fields[userOwner]=id.
convert_relation_table_name_strategy: ключ связи — таблица связанной модели, преобразованная по snake_case, camelCase или none. null отключает эту настройку.
convert_field_names_to_snake_case: преобразовывать запрошенные имена полей, чтобы firstName выбирал first_name.

См. Выбор полей.

Переводы

Сообщения об ошибках definitions API переведены на английский и русский и следуют локали приложения. Чтобы изменить формулировки или добавить язык, опубликуйте переводы в lang/vendor/query-builder:

bash

php artisan vendor:publish --tag=query-builder-translations

См. Ошибки.

Установка и настройка ​