Введение

Эндпоинт API, отдающий список записей, обычно позволяет клиенту выбрать, что он получит:

GET /users?filter[name]=john&sort=-created_at&include=posts&fields[users]=id,name&fields[posts]=title

Пакет читает эти параметры, проверяет их по тому, что разрешает эндпоинт, и применяет к Eloquent-запросу. Параметр, который эндпоинт не разрешает, отклоняется и не доходит до базы данных.

Прямая замена spatie/laravel-query-builder

API пакета совместим с spatie/laravel-query-builder 7.x: те же имена классов, сигнатуры методов, исключения и файл конфигурации. Для перехода достаточно сменить неймспейс: Spatie\QueryBuilder → MyProgs\QueryBuilder. Код, написанный для spatie 5 и 6, тоже работает. Тестовый набор spatie гоняется против этого пакета как контракт совместимости.

Подгруженные связи никогда не пусты

В spatie набор полей вместе с include теряет связанные записи:

GET /users?fields[users]=name&include=posts

Пользователи выбираются без id, Eloquent не может сопоставить с ними посты, и каждая связь posts приходит пустой. То же происходит, когда fields[posts] не содержит user_id. Это issue #175 в spatie.

Этот пакет добавляет в SELECT первичные и внешние ключи, нужные каждой подгруженной связи: для belongsTo, hasMany, morphTo, pivot у belongsToMany, hasManyThrough и остальных. Подгруженные связи загружаются так, как если бы набор полей перечислял ключи.

Два API над одним ядром

• Spatie-совместимый API (QueryBuilder::for(User::class)->allowedFilters(...)) предназначен для существующего кода и прямой замены. См. Основы использования.
• Definitions API (UserQuery::for($request)) описывает в одном классе, что запрос клиента может получить от ресурса. Он добавляет типизированные фильтры с операторами (filter[price][gte]=100), сортировки по связям и агрегатам, виртуальные поля, вложенные определения, встроенную пагинацию и сообщает обо всех ошибках запроса в одном ответе 422. См. Описание запросов.

Оба API разбирают, проверяют и планируют запрос одним и тем же ядром, поэтому ключи добавляются в обоих одинаково.

Требования

• PHP 8.3 или новее
• Laravel 12 или 13