Выбор полей

allowedFields() перечисляет колонки, которые может выбрать запрос клиента. Параметр fields[<key>] принимает список колонок для корневой модели и для каждой подгруженной связи:

QueryBuilder::for(User::class)
    ->allowedFields('id', 'name', 'email', 'posts.id', 'posts.title')
    ->allowedIncludes('posts')
    ->get();

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

select "users"."name", "users"."id" from "users"
select "posts"."title", "posts"."user_id" from "posts" where "posts"."user_id" in (...)

Поле не из списка выбрасывает InvalidFieldQuery. Без fields[...] выбираются все колонки.

Ключи

Ключ корня — его таблица, fields[users]. Ключ подгруженной связи — её имя в snake case во множественном числе: include=userOwner принимает fields[user_owners]. Настройка позволяет задавать ключи связей по имени в том виде, как оно написано, или по таблице связанной модели.

В allowedFields() колонки связи пишутся с именем связи впереди: posts.title.

Ключи связей добавляются

Запрос выше просит только users.name, но пользователи выбираются с id, а посты — с user_id: без них Eloquent не смог бы сопоставить посты с их пользователями. Покрыт каждый тип связи, включая morphTo, pivot у belongsToMany и связи through. Добавленные ключи — обычные атрибуты загруженных моделей; скройте их в API-ресурсах, если их нельзя отдавать клиенту.

В spatie тот же запрос возвращает пользователей с пустыми posts. См. Введение.

Порядок вызовов

allowedFields() и allowedIncludes() можно вызывать в любом порядке: оба применяются непосредственно перед выполнением запроса.

Поля связи в коде

getRequestedFieldsForRelatedTable('posts') возвращает колонки, которые запрос клиента указал для связи, — для кода, который загружает её вручную.