JsonRpcBundle

composer require ufo-tech/json-rpc-bundle

PHP 8.4+
Symfony 7.2+ · 8
Протокол JSON-RPC 2.0 · OpenRPC
Тип Symfony Bundle
Категорія API
Ліцензія MIT

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

JSON-RPC 2.0 сервер для Symfony 7.2+ / 8 (PHP 8.4+).

Робити RPC сервіси для сервіс-орієнтованої архітектури на Symfony ще ніколи не було так просто.

Будь-який сервіс вашого застосунку стає API: реалізуйте інтерфейс IRpcService — і його публічні методи доступні як JSON-RPC методи. Валідація, перетворення типів, безпека, кеш і документація OpenRPC беруться з коду, який ви вже написали.

Від класу до API

Ваш код

#[RPC\Info('User')]
final class UserApi implements IRpcService
{
    public function __construct(private UserService $users) {}

    /**
     * Returns a user by id
     * @throws UserNotFoundException
     */
    #[RPC\Cache(lifetimeSecond: RPC\Cache::T_HOUR)]
    public function get(int $id): UserDto
    {
        return $this->users->get($id);
    }
}

Запит

{"jsonrpc": "2.0", "id": 1, "method": "User.get", "params": {"id": 5}}

Відповідь

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {"id": 5, "email": "user@example.com", "name": "John"}
}

Більше нічого писати не треба:

GET /rpc уже повертає документацію OpenRPC з методом User.get, схемою UserDto і помилкою з @throws, а GET /rpc/postman — готову колекцію Postman;
неправильний тип id поверне помилку -32602 з поясненням по параметру;
у prod-оточенні відповідь кешується на годину;
той самий метод можна викликати з консолі, з черги Symfony Messenger, у batch разом з іншими методами — і, через розширення, як REST-ендпоінт чи інструмент для AI-агента.

Чому JsonRpcBundle

Документація не відстає від коду. OpenRPC і Postman будуються з типів PHP, PHPDoc, DTO, enum і обмежень валідації; назви методів перекладаються за Accept-Language (Документація API).
Один метод — багато транспортів. HTTP, консоль, Symfony Messenger, а через розширення — REST, MCP, Mercure (Асинхронність, Виклик з консолі).
Еволюція без болю. Кілька версій API поруч (/rpc, /rpc/v2) і кілька груп API в одному застосунку — публічна, внутрішня, BFF — зі своїми методами й токенами.
Менше запитів по мережі. Batch із залежностями @FROM:<id>(<поле>), notifications «вистрілив і забув», результат на webhook.
Декларативність замість рутини. Валідація, DTO й конвертація типів, кеш і блокування — атрибутами на методі.
Розширюваність. Події навколо кожного виклику й точки розширення ядра (Для розробників).

Версія 10.4

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

Переклади для груп API: translations/rpc/<group>.<locale>.yaml; група важливіша за мову.
Переклади з розширень (translations.paths), публічний сервіс RpcLocaleNegotiator.
10.4.1: IApiRouteImport — маршрути адаптера можна підключити окремо для кожної групи API.
10.4.2: RpcExecutor — єдина точка входу для адаптерів (REST, MCP); rpc.post_response запускається для будь-якого джерела запиту і для кожного виконаного елемента batch.

Що врахувати

Частковий базовий переклад: відсутній description береться з базового перекладу мовою kernel.default_locale, а не з атрибута / PHPDoc.
REST-виклики тепер отримують rpc.post_response: для них запрацюють зв'язки кешу й async/notification-лістенери.

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

Без змін відносно 10.3.

Екосистема

AI-агенти. MCP Bundle відкриває ваші RPC-методи як інструменти для Claude Code, Cursor, Gemini CLI та OpenAI — без окремого коду.
REST. REST Bundle публікує вибрані методи як REST API з документацією OpenAPI.
Клієнти. JSON-RPC Client SDK генерує PHP-клієнт з класами процедур і DTO, RPC TS SDK — TypeScript-інтерфейси з документа OpenRPC.
Правила для ШІ-асистентів. Файли інструкцій, щоб Claude Code, Codex чи Cursor правильно працювали з бандлом.

Повний перелік — на сторінці Розширення.

З чого почати

Встановіть бандл — composer require ufo-tech/json-rpc-bundle і два конфігураційні файли.
Додайте власні методи і відкрийте GET /rpc, щоб побачити документацію.
Налаштуйте безпеку й інші параметри.
Перегляньте можливості: batch, notifications, асинхронність, події.

Не впевнені, чи підходить вам JSON-RPC? Прочитайте статтю RPC, REST та GraphQL — коротко й практично про те, коли який підхід доречний.