Готьє Делегліз (Gautier Deleglise) випустив Laravel Rest Api 3.0 - пакет lomkit/laravel-rest-api, який робить з Eloquent-моделі повне REST API: пошук, запис, дії, видалення, і все це з одного класу ресурсу, без ручних контролерів. Ідея лишилася тією ж, а от усе, що під нею, автор переписав: тепер одне оголошення поля відповідає і за фільтри, і за валідацію, і за документацію.
Для команд, які пишуть внутрішні чи партнерські API, це відчутна альтернатива зв'язці «контролер + Form Request + API Resource + окремо написаний OpenAPI». Перший огляд випуску зробив Laravel News, ми ж пройшлися по нотатках випуску та посібнику з оновлення.
Типізовані поля замість списку стовпців
У 2.x ресурс просто перелічував назви стовпців. У 3.0 fields() повертає об'єкти полів: ID, Text, Integer, Number, Boolean, Date, DateTime, Enum, Json.
public function fields(): array
{
return [
ID::make('id'),
Text::make('title')->rules('max:80')->creationRules('required'),
Integer::make('seats')->rules('min:0'),
Enum::make('status', ShowStatus::class)
->offered([ShowStatus::Planned, ShowStatus::OnSale]),
Date::make('starts_on')->creationRules('required'),
];
}
З цього одного оголошення пакет виводить решту:
- фільтри приймають лише оператори, що пасують типу поля, а все інше отримує
422;
- валідація запису вказує точний шлях до помилки, наприклад
mutate.0.attributes.seats;
- відповіді повертають значення у своєму типі: числа - числами, а порожнє JSON-поле - як
{}, а не [];
Enum::offered() обмежує, які варіанти клієнт може записати. Варіант, що випав зі списку, лишається доступним для читання, фільтрів і сортування на старих рядках, але записати його вже не вийде.
Останнє - дрібниця, яка в ручному коді зазвичай забувається: статус виводять з ужитку, а старі записи з ним ламають валідацію при будь-якому оновленні.
Документація OpenAPI через Scramble
Вбудований генератор документації прибрали разом з маршрутом /api-documentation і командою rest:documentation. Замість нього пакет інтегрується зі Scramble (потрібна версія 0.13.48 або новіша з гілки 0.13): після встановлення на /docs/api з'являється опис кожного ендпоїнта кожного ресурсу з типізованим тілом, правилами полів, прикладами запитів і відповідями з помилками.
Цікава деталь із нотаток випуску: тести самого пакета відправляють ці приклади запитів до API і звіряють відповіді з документом. Якщо документація розійдеться з поведінкою, впаде тест.
Метрики без контролерів
Метрики - нова можливість 3.0. Метрику оголошують на ресурсі, і вона отримує власний маршрут POST {name}/metrics/{uriKey}:
class ShowsByStatus extends Partition
{
public function calculate(Builder $query): PartitionResult
{
return $this->count($query, 'status');
}
}
Типів п'ять: Value, Trend, Partition, Progress і Table. Вони рахують кількість, суми, середні, медіани й перцентилі, підтримують діапазони дат, часові пояси, порівняння з попереднім періодом і кеш результату. Важливо, що метрика рахує лише ті рядки, які поточний користувач і так бачить, а клієнт може звузити вибірку тими самими фільтрами, що й у пошуку. Для адмінських дашбордів це знімає цілий клас ендпоїнтів, написаних «на швидку руку» без перевірки прав.
Підтвердження небезпечних дій
Дія, mutate, destroy, restore чи forceDestroy тепер можуть попросити підтвердження перед виконанням:
public function destroyConfirmation(Collection $models): ?Confirmation
{
return Confirmation::make("Delete {$models->count()} shows and their tickets?");
}
Перший запит отримує відповідь 428 з повідомленням і підписаним токеном. Клієнт показує користувачеві діалог і повторює той самий запит уже з токеном - тоді операція виконується. Ні сесії, ні окремого ендпоїнта для підтвердження.
Серед інших змін:
- політики перевіряються на кожному ресурсі, якого торкається запит, і на кожному рядку запису ще до першої зміни в базі, а
perimeterQuery() обмежує ресурс орендарем чи командою на будь-якому рівні вкладеності;
- один запис може створити, оновити, прив'язати й видалити дочірні рядки в одній транзакції, а ресурси з
versioned() повертають 409, якщо рядок змінився після того, як клієнт його прочитав;
Rest::search() повторює збережений пошук поза HTTP, наприклад у завданні черги чи експорті, з тими самими правилами й політиками;
- повнотекстовий пошук працює через
LIKE, індекси MySQL, MariaDB і PostgreSQL або Meilisearch, Typesense та Algolia через Scout;
php artisan rest:quick-start читає таблиці й генерує ресурси, контролери, стартові політики та маршрути, а php artisan rest:check ловить у CI відсутню політику чи периметр;
- є навичка для Laravel Boost, щоб ШІ-асистент писав ресурси так, як очікує пакет.
Міграція з 2.x
Вимоги: PHP 8.3+ і Laravel 13.30+, ліцензія MIT. Проєкти на Laravel 12 лишаються на 2.x, а на ранішому Laravel 13 спершу оновлюють сам фреймворк.
composer require lomkit/laravel-rest-api:^3.0
Посібник з оновлення - це понад дві з половиною тисячі рядків, розбитих за розділами пакета. Найпомітніші зміни:
fields() повертає об'єкти Field: рядок кидає InvalidFieldException, а nullable-стовпцям треба додати ->nullable();
- оголошення ресурсу більше не приймають
RestRequest $request, а запит читається через $this->request(). Перевизначення зі старою сигнатурою PHP просто не завантажить;
Rest::resource() приймає два аргументи, а масив опцій замінили на only(), except(), names(), middleware(). Третій аргумент PHP мовчки ігнорує, тож забутий ['except' => ['destroy']] зареєструє destroy - варто пройтися пошуком по файлах маршрутів;
- з
config/rest.php зникли authorizations.enabled і gates.enabled (тепер перевизначають isAuthorizingEnabled() і isGatingEnabled()), з'явилася група limits;
- ендпоїнт примусового видалення перейменовано на
forceDestroy, а кожна дія й метрика тепер має власний маршрут - після змін у них при кешованих маршрутах треба знову запускати php artisan route:cache.
Зважте й на темп випусків: уже 10 листопада вийшли 3.0.1 з виправленнями авторизації та 3.1.0, у якому rest:check став суворішим: зв'язок, що дозволяє detach на NOT NULL зовнішньому ключі, тепер валить перевірку. Ресурси, згенеровані в 3.0, після оновлення можуть зламати CI, доки не додати ->withoutOperations(MutationOperation::Detach).
Кому брати, а кому ні
Пакет добре лягає там, де API - це здебільшого CRUD над моделями з фільтрами, пошуком і правами доступу: внутрішні панелі, бекенд для SPA чи мобільного клієнта, партнерські інтеграції, де потрібна актуальна OpenAPI-специфікація.
Гірше він підходить, коли ендпоїнти не віддзеркалюють моделі: складна бізнес-логіка зі сценаріями на кілька кроків, агрегати з різних джерел, відповіді у форматі, який диктує зовнішній стандарт. Пакет має власний формат запитів (search, mutate з вкладеними операціями) і власну форму відповідей, тож клієнт прив'язується до нього. Якщо API публічне й має жити довше за вибір бібліотеки, це варто зважити заздалегідь.
Тим, хто лишається на 2.x, варто перевірити версію: у серпні вийшла 2.23.2 з виправленням GHSA-w87g-c4fx-87gg - вкладені sync і toggle могли записувати в пов'язану модель неавторизовані й неперевірені атрибути (уражені версії від 2.0.0 до 2.23.1). А тим, хто мігрує, - почати з rest:check у CI і брати одразу 3.1, а не 3.0.0. Повна документація - на laravel-rest-api.lomkit.com.