REST Bundle

REST Bundle

Версія Завантаження Зірки

composer require ufo-tech/rest-bundle
  • PHP 8.4+
  • Symfony 7.2+ · 8
  • Основа JsonRpcBundle 10.4.3+
  • Протокол REST · OpenAPI · Postman
  • Тип Symfony Bundle
  • Категорія API
  • Ліцензія MIT

GitHub Packagist Історія змін Відомі помилки

REST API поверх методів JsonRpcBundle для Symfony 7.2+ / 8 (PHP 8.4+).

RPC-метод лишається єдиною реалізацією: атрибут Symfony #[Route] на методі RPC-процедури робить його доступним за власним шляхом і HTTP-методом. Параметри, валідація, безпека, кеш, події та документація беруться з ядра RPC; бандл додає HTTP-маршрути, REST-формат запитів і відповідей, помилки RFC 9457 і документи OpenAPI 3.1 та Postman.

Документація описує версію 1.3, яка ще не має тегу (останній реліз — 1.2.0). Те, що з'явилось лише в 1.3, позначено на сторінках. Див. Історію змін.

Від методу до REST

Ваш код

use Symfony\Component\Routing\Attribute\Route;
use Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService;
use Ufo\RpcObject\RPC;

#[RPC\Info('catalog')]
#[Route('/catalog', name: 'catalog')]
class CatalogApi implements IRpcService
{
    #[Route('/items/{id}', name: 'item', methods: ['GET'])]
    public function item(int $id): array
    {
        return ['id' => $id, 'title' => 'Book'];
    }
}

Запит

curl https://example.com/rest/catalog/items/42 \
  -H 'Ufo-RPC-Token: change-me'

Відповідь 200

{"id": 42, "title": "Book"}

Що ви отримуєте без додаткового коду:

  • GET /rest повертає документ OpenAPI 3.1 з операцією catalog.item, а GET /rest/postman — колекцію Postman;
  • значення 42 зі шляху приводиться до int за сигнатурою методу (з 1.3);
  • помилки — RFC 9457 problem details з HTTP-статусом (401, 404, 405, 422, …);
  • той самий метод і далі доступний через JSON-RPC: POST /rpc з "method": "catalog.item".

Чому REST Bundle

  • Одна реалізація — два протоколи. Немає REST-контролера на кожен метод, другого набору DTO чи окремої валідації. #[RPC\Assertions], #[RPC\Cache], #[RPC\Lock] і події працюють для REST так само, як для JSON-RPC.
  • Публікація явна. У REST потрапляє лише метод з #[Route]; решта лишається тільки в RPC (Маршрутизація).
  • Групи й версії API. Окремий REST-вхід для кожної групи API з власними методами, документацією і токенами; версії під /v2/....
  • Документація з коду. OpenAPI і Postman будуються з RPC service map: типи, PHPDoc, @throws, переклади (Документація API).
  • Без окремої конфігурації. Бандл використовує налаштування ufo_json_rpc: безпеку, назву проєкту, переклади (Налаштування).

Версія 1.2

Тег 1.2.0, 2026-10-16.

Ключові зміни

  • Підтримка Symfony 8: ^7.2|^8.0.
  • Колекція Postman будується на AbstractPostmanAdapter JsonRpcBundle: назва REST: <project_name>, для групи, відмінної від general, — із суфіксом [група].
  • composer test і make test запускають PHPUnit.

Що врахувати

  • Інструменти, що шукають колекцію Postman за назвою, побачать нову назву.

Зміни оточення

  • ufo-tech/json-rpc-bundle ^10.2.3.
  • Symfony ^7.2 або ^8.0.

З чого почати

  1. Встановіть бандл — composer require ufo-tech/rest-bundle і файл маршрутів.
  2. Додайте #[Route] до потрібних методів (Маршрутизація) і відкрийте GET /rest.
  3. Перегляньте, як передаються параметри і як повертаються помилки.
  4. Налаштуйте безпеку.

Через REST недоступні JSON-RPC batch, notifications і $rpc.callback: один HTTP-запит — один виклик методу.

Як бандл влаштований усередині і як його розширювати — у розділі Для розробників. Коли доречний REST, а коли RPC, — у статті RPC, REST та GraphQL.