Увійти Реєстрація
Вакансії
Вакансії Laravel Компанії Статистика
Підготовка
Як підготуватися Співбесіди Тестування Документація
Блог
Всі статті Серії
Екосистема
Пакети Ресурси Проєкти Інструменти Події Відео
Інше
Про нас Реклама
Новини 13 листопада 2026

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

Готьє Делегліз (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.

12

Читати в документації

Коментарі

Увійдіть, щоб залишити коментар

Будьте першим, хто залишить коментар!

Читайте також

Laravel 13.43
Новини 19 листопада 2026

Laravel 13.43 і 12.73: серія виправлень безпеки, від масового присвоєння до підписаних URL

Laravel 13.43.0 і 12.73.0 закривають обхід захисту масового присвоєння через мутатори, ще одну дірку в терміні дії підписаних URL, DoS у JsonSchema і XSS на debug-сторінці. Кілька правил валідації exists, unique і not_regex після оновлення можуть поводитися суворіше.

20
Laravel 13.43
Новини 19 листопада 2026

Laravel 13.43: атрибут RetryFor, releaseUsingBackoff() і повтори Predis після обриву з'єднання

Laravel 13.43.0 додає атрибут #[RetryFor] замість методу retryUntil() і releaseUsingBackoff() для завдань, що самі повертаються в чергу. Predis тепер повторює безпечні команди після втрати з'єднання, а JsonSchema::rules() виводить правила валідації прямо зі схеми.

13

Вакансії за темою

LUMICODE KYIV Нова
Сьогодні

Full Stack PHP Developer

Розробка та розвиток вебплатформи продажу й управління проксі-сервісами: серверна частина на PHP, REST API для інтеграцій, бізнес-логіка купівлі, оренди та видачі проксі, платіжні інтеграції й автоматизація перевірки якості проксі. Також доопрацювання UI/UX та особистого кабінету. Вимоги: комерційний Full Stack досвід від 3 років, впевнене знання PHP 8+, ООП, SOLID, практика з Laravel або Symfony, JavaScript/TypeScript та React/Vue.js, робота з MySQL/PostgreSQL, Docker, Git.

halsoft.net Нова
2 дні тому

Shopify Apps Developer

Розробка веб-застосунків і Shopify-застосунків для власників магазинів Shopify: бекенд-сервіси на PHP Laravel, фронтенд на React, інтеграція з магазинами Shopify, RESTful API та код-ревʼю. Вимоги: досвід Shopify-застосунків, знання Node.js, Laravel, ReactJS, Vue.js, HTML, CSS, JavaScript, Git і портфоліо проєктів. На старті роботa на неповну ставку.

Starlight Media Нова
2 дні тому

Senior Full-Stack Developer (PHP / Go / Vue.js)

Senior Full-Stack розробник матиме розвивати й підтримувати існуючі веб-платформи, писати модулі, сервіси та API, а також розробляти клієнтську частину на Vue.js і Vanilla JS. Основний стек: PHP 8.x з Yii2 та/або Laravel, Go для сервісів, MySQL/MariaDB, REST API і Webhooks. Вимоги: досвід від 3 років, знання ООП і шаблонів проєктування, ES6+, Vue.js, SPA, Git, Docker і Composer; англійська B1-B2.

Пакети за темою

L5 Swagger

darkaonline/l5-swagger

Інтеграція OpenApi або Swagger у Laravel для документування API додатків.

2,933 11.4.1 13 6

Kalimera

welldigit/kalimera

Interactive installer that scaffolds Laravel applications the Well Digit way.

v1.0.0 17