---
title: "Laravel Rest Api 3.0: типізовані поля, метрики й OpenAPI через Scramble"
url: https://laravelukraine.com/blog/laravel-rest-api-30-tipizovani-polia-metriki-i-openapi-cerez-scramble
date: 2026-11-13
---

# Laravel Rest Api 3.0: типізовані поля, метрики й OpenAPI через Scramble

Готьє Делегліз (Gautier Deleglise) [випустив Laravel Rest Api 3.0](https://github.com/Lomkit/laravel-rest-api/releases/tag/v3.0.0) - пакет `lomkit/laravel-rest-api`, який робить з Eloquent-моделі повне REST API: пошук, запис, дії, видалення, і все це з одного класу ресурсу, без ручних контролерів. Ідея лишилася тією ж, а от усе, що під нею, автор переписав: тепер одне оголошення поля відповідає і за фільтри, і за валідацію, і за документацію.

Для команд, які пишуть внутрішні чи партнерські API, це відчутна альтернатива зв'язці «контролер + Form Request + API Resource + окремо написаний OpenAPI». Перший огляд випуску зробив [Laravel News](https://laravel-news.com/laravel-rest-api-3), ми ж пройшлися по нотатках випуску та [посібнику з оновлення](https://github.com/Lomkit/laravel-rest-api/blob/3.x/UPGRADE.md).

### Типізовані поля замість списку стовпців

У 2.x ресурс просто перелічував назви стовпців. У 3.0 `fields()` повертає об'єкти полів: `ID`, `Text`, `Integer`, `Number`, `Boolean`, `Date`, `DateTime`, `Enum`, `Json`.

```php
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](https://scramble.dedoc.co/) (потрібна версія 0.13.48 або новіша з гілки 0.13): після встановлення на `/docs/api` з'являється опис кожного ендпоїнта кожного ресурсу з типізованим тілом, правилами полів, прикладами запитів і відповідями з помилками.

Цікава деталь із нотаток випуску: тести самого пакета відправляють ці приклади запитів до API і звіряють відповіді з документом. Якщо документація розійдеться з поведінкою, впаде тест.

### Метрики без контролерів

Метрики - нова можливість 3.0. Метрику оголошують на ресурсі, і вона отримує власний маршрут `POST {name}/metrics/{uriKey}`:

```php
class ShowsByStatus extends Partition
{
  public function calculate(Builder $query): PartitionResult
  {
    return $this->count($query, 'status');
  }
}
```

Типів п'ять: `Value`, `Trend`, `Partition`, `Progress` і `Table`. Вони рахують кількість, суми, середні, медіани й перцентилі, підтримують діапазони дат, часові пояси, порівняння з попереднім періодом і кеш результату. Важливо, що метрика рахує лише ті рядки, які поточний користувач і так бачить, а клієнт може звузити вибірку тими самими фільтрами, що й у пошуку. Для адмінських дашбордів це знімає цілий клас ендпоїнтів, написаних «на швидку руку» без перевірки прав.

### Підтвердження небезпечних дій

Дія, `mutate`, `destroy`, `restore` чи `forceDestroy` тепер можуть попросити підтвердження перед виконанням:

```php
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 спершу оновлюють сам фреймворк.

```bash
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](https://github.com/Lomkit/laravel-rest-api/releases/tag/v3.0.1) з виправленнями авторизації та [3.1.0](https://github.com/Lomkit/laravel-rest-api/releases/tag/v3.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](https://github.com/Lomkit/laravel-rest-api/security/advisories/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](https://laravel-rest-api.lomkit.com).
