PHPackages tochka-developers/jsonrpc - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. tochka-developers/jsonrpc ActiveLibrary[API Development](/categories/api) tochka-developers/jsonrpc ========================= JsonRpc extension for Laravel v5.1.0(1mo ago)2834.5k↓38.5%20[1 PRs](https://github.com/tochka-developers/jsonrpc/pulls)1MITPHPPHP 8.2.\*|8.3.\*|8.4.\*CI failing Since Jun 8Pushed 4w ago5 watchersCompare [ Source](https://github.com/tochka-developers/jsonrpc)[ Packagist](https://packagist.org/packages/tochka-developers/jsonrpc)[ RSS](/packages/tochka-developers-jsonrpc/feed)WikiDiscussions v5 Synced 2w ago READMEChangelog (10)Dependencies (23)Versions (98)Used By (1) JSON-RPC Server (Laravel/Lumen) =============================== [](#json-rpc-server-laravellumen) [![Quality Gate Status](https://camo.githubusercontent.com/fd32d558d8dd3448e231a17309bad09d0303916f811ea6b9428c8532ab07b8dc/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d746f63686b612d646576656c6f706572735f6a736f6e727063266d65747269633d616c6572745f737461747573)](https://sonarcloud.io/dashboard?id=tochka-developers_jsonrpc)[![Bugs](https://camo.githubusercontent.com/f8fcd7e5f903e44f74895c9c1d71697d8bd7dc5cf1f7325e41453be6a282ed89/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d746f63686b612d646576656c6f706572735f6a736f6e727063266d65747269633d62756773)](https://sonarcloud.io/dashboard?id=tochka-developers_jsonrpc)[![Code Smells](https://camo.githubusercontent.com/e8f83d397cf91cb99035a0e6af9ff1e63d87359fdcfc462cfbe664d46e7161e8/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d746f63686b612d646576656c6f706572735f6a736f6e727063266d65747269633d636f64655f736d656c6c73)](https://sonarcloud.io/dashboard?id=tochka-developers_jsonrpc)[![Coverage](https://camo.githubusercontent.com/558d03959866eedc44d9694fbd464deada92add57e2e0c97eeb547c908272515/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d746f63686b612d646576656c6f706572735f6a736f6e727063266d65747269633d636f766572616765)](https://sonarcloud.io/dashboard?id=tochka-developers_jsonrpc) Описание ======== [](#описание) JsonRpc сервер - реализация сервера по спецификации JsonRpc 2.0. Поддерживаемые версии: - Laravel >= 10.0 - PHP >= 8.2 Поддерживает: - вызов удаленных методов по нотификации имяКонтроллера\_имяМетода, либо с разделением логики на несколько ресурсных точек входа - вызов нескольких удаленных методов в одном запросе - передача параметров в метод контроллера по имени - маппинг параметров в DTO - аутентификация с помощью токена, переданного в заголовке - контроль доступа по IP-адресам - контроль доступа к методам для разных сервисов - ACL - возможность поддержки нескольких серверов в рамках одно сервиса - расширение возможностей с помощью механизма Middleware - кеширование всех роутов для увеличения быстродействия Установка ========= [](#установка) Установка через composer: ``` composer require tochka-developers/jsonrpc ``` ### Laravel [](#laravel) Для Laravel есть возможность опубликовать конфигурацию для всех пакетов: ``` php artisan vendor:publish ``` Для того чтобы опубликовать только конфигурацию данного пакета, можно воспользоваться опцией tag ``` php artisan vendor:publish --tag="jsonrpc-config" ``` Настройка точек входа ===================== [](#настройка-точек-входа) Пропишите в вашем route.php: ``` \Route::post('/v1/public/jsonrpc', function (Request $request) { $server = new JsonRpcServer(ServerConfig::makeFromConfigFile('default')); return $server->handle($request->getContent()); }); ``` Конфигурация ============ [](#конфигурация) ``` return [ // можно настроить несколько разных конфигурация для разных точек входа, // чтобы указать в маршруте, какая именно конфигурация должна быть использована - используйте имя при создании сервера 'default' => [ // Краткое описание сервера 'summary' => 'Основная точка входа', // Полное описание сервера 'description' => 'Основная точка входа', // Namespace, в котором находятся контроллеры 'namespace' => 'App\\Http\\Controllers\\Api\\', // Suffix для контроллеров 'controllerSuffix' => 'Controller', // Разделитель для имен методов 'methodDelimiter' => '_', // Использовать методы родителя при наследовании 'allowParentMethods' => false, // список Middleware, обрабатывающих запросы // описание middleware ниже 'middleware' => [ // Tochka\JsonRpc\Middleware\LogMiddleware::class => [ // Канал лога, в который будут записываться все логи 'channel' => 'default', // Заголовки которые нужно писать в лог 'headers' => ['accept', 'encoding'] ], Tochka\JsonRpc\Middleware\TokenAuthMiddleware::class => [ 'headerName' => 'X-Tochka-Access-Key', // Ключи доступа к API 'tokens' => [ 'troll' => env('JSONRPC_KEY_TROLL', ''), ], ], Tochka\JsonRpc\Middleware\AccessControlListMiddleware::class => [ 'acl' => [ '*' => '*', FooController::class => ['service'], FooController::class . '@method' => ['service2'], ], ], ], ], ]; ``` Обработчики (Middleware) ======================== [](#обработчики-middleware) Обработчики позволяют подготовить запрос, прежде чем вызывать указанный метод. Список обработчиков задается в параметре `jsonrpc.middleware`. Это массив, в котором необходимо перечислить в порядке очереди классы обработчиков. По умолчанию доступны следующие обработчики: - `Tochka\JsonRpc\Middleware\LogMiddleware` - логирование входящих запросов - `Tochka\JsonRpc\Middleware\TokenAuthMiddleware` - авторизация сервиса по токену в заголовке - `Tochka\JsonRpc\Middleware\ServiceValidationMiddleware` - валидация сервиса по его IP-адресу - `Tochka\JsonRpc\Middleware\AccessControlListMiddleware` - ACL - правила доступа разных сервисов к разным методам и группам Jsonrpc-сервера Кроме того, вы можете использовать свои Middleware для любых других целей (авторизация через BasicAuth, дополнительная фильтрация/валидация данных, etc) ### Аутентификация по токену (TokenAuthMiddleware) [](#аутентификация-по-токену-tokenauthmiddleware) Необходима, если вы хотите ограничить доступ к сервису и использовать в качестве аутентификации доступ по токену в заголовке. В конфигурацию обработчика передаются следующие параметры: ``` [ 'headerName' => 'X-Tochka-Access-Key', 'tokens' => [ 'service_foo' => env('JSONRPC_KEY_SERVICE_FOO', \Str::uuid()->toString()), 'service_bar' => env('JSONRPC_KEY_SERVICE_BAR', \Str::uuid()->toString()), ] ``` - `headerName` - имя заголовка, в котором клиент должен передать токен - `tokens` - список сервисов-клиентов и их токены Если запрос был осуществлен без данного заголовка, либо с токеном, которого нет в списке - клиенту вернется ошибка. Если аутентификация прошла успешно - клиент будет опознан как `service_foo` (`service_bar`), что позволит контролировать доступ к методам. Если аутентификация отключена - клиент будет опознан как `guest`. ### Валидация сервиса по IP (ServiceValidationMiddleware) [](#валидация-сервиса-по-ip-servicevalidationmiddleware) Подключайте, если необходимо ограничить список IP-адресов, с которых сервис-клиент может осуществлять запросы. В конфигурацию обработчика передаются следующие параметры: ``` [ 'servers' => [ 'service_foo' => ['192.168.0.1', '192.168.1.5'], 'service_bar' => '*', ], ] ``` В указанном примере авторизоваться с ключом доступа сервиса `service_foo` могут только клиенты с IP адресами `192.168.0.1` и `192.168.1.5`. Сервис `service_bar` может авторизоваться с любых IP адресов. ### Контроль доступа к методам (AccessControlListMiddleware) [](#контроль-доступа-к-методам-accesscontrollistmiddleware) Если включен обработчик `AccessControlListMiddleware`, то будет осуществлен контроль доступа к методам. В конфигурацию обработчика передаются следующие параметры: ``` [ 'acl' => [ '*' => ['service1', 'service2'], 'App\Http\TestController' => ['service1'], 'App\Http\TestController@isActivationAllowed' => ['service2'], ] ] ``` ### Логирование - LogMiddleware [](#логирование---logmiddleware) Для логирования входящих запросов используется LogMiddleware. В конфигурацию обработчика передаются следующие параметры: ``` [ 'channel' => 'jsonrpc', 'hideParams' => [ UserController::class => ['password', 'old_password', 'new_password'], ], ] ``` - `channel` - канал логирования. Любой из каналов, описанных в конфигурации `logging.php` - `hideParams` - скрывает из логирования указанные параметры (в случае конфиденциальных данных). Описывается с помощью ассоциативного массива, в котором ключами выступает целевой метод, в котором необходимо скрыть параметры, а значения - имена параметров, которые необходимо скрыть. В качестве ключей может быть: - `*` - правило распространяется для всего сервера (для всех контроллеров и методов) - `App\Http\Controllers\UserController` - правило распространяется для всех методов указанного контроллера - `App\Http\Controllers\UserController@auth` - правило распространяется для указанного метода в указанном контроллере Маршрутизация (роутинг) ======================= [](#маршрутизация-роутинг) Для ускорения поиска нужного метода и правильной просадки параметров пакет генерирует список всех маршрутов с описанием этих параметров. Для вывода всех доступных маршрутов вы можете воспользоваться командой artisan `jsonrpc:route:list {?server}`: ``` > php artisan jsonrpc:route:list +---------------------------+-----------------------------------------+----------------------+ | Method | Controller | Call | +---------------------------+-----------------------------------------+----------------------+ | user_test1 | App\Http\Controllers\Api\UserController | test1 | | user_test2 | App\Http\Controllers\Api\UserController | test2 | | user_test4 | App\Http\Controllers\Api\UserController | test4 | +--------------------------------------------------------------------------------------------+ ``` При каждом входящем запросе схема маршрутов заново пересчитывается. Чтобы этого не происходило, необходимо закешировать все маршруты с помощью команды `jsonrpc:route:cache {?serverName}`. Построенная схема сохранится в файл и будет использоваться каждый раз при следующих запросах. Учтите это при разработке - пока есть построенная закешированная схема маршрутов - любые изменения маршрутов в коде не будут отражаться на выполнении запросов. Рекомендуется выполнять команду кеширования маршрутов сразу после деплоя на рабочие инстансы (по аналогии с командой Laravel `config:cache`). Чтобы очистить кеш - выполните команду `jsonrpc:route:clear {?serverName}`. После очистки кеша маршруты снова будут строиться каждый раз при входящем запросе. Маппинг параметров ================== [](#маппинг-параметров) При запросе, сервер берём все параметры указанные в методе и пытается просадить их в метод. Все параметры которые не указаны в методе будут проигнорированы. При создании списка маршрутов для каждого параметра определяется тип и в зависимости от типа входной параметр будет проверен и подставлен в метод. ### Тип параметра Mixed [](#тип-параметра-mixed) Тип параметра не указан или указан как mixed. Просто подставляем. ``` /** * В этом примере два входных параметра, оба могут быть любого типа * */ public function test1($a, mixed $b) { //.... } ``` ### Тип параметра Primitive [](#тип-параметра-primitive) Тип параметра примитив, так же может быт UnionType из примитивов (int|string|bool) ``` /** * Пример простых типов * */ public function test1(int $a, string $b, ?string $c, bool|string|int|float|object $d) { //.... } ``` ### Тип параметра Enum [](#тип-параметра-enum) Будет создан экземпляр указанного Enum`a ``` /** * Будет создан экземпляр MyEnum * */ public function test1(MyEnum $a) { //.... } ``` ### Тип параметра Object [](#тип-параметра-object) Параметром является объект который будет создан сервером. При этом тип должен быть задан явно и не содержать перечисления типов. В таком случае создаётся неоднозначность того что должно быть создано. Если вам нужно создавать разные объекты в зависимости от какой-то логики, то лучше обернуть это в объект обёртку. ``` /** * Тут сервер попытается создать объект указанного класса. * */ public function test1(SomeObject $a) { //.... } ``` ``` /** * Такое работать не будет * @deprecated */ public function test1(SomeObject|SomeObject2 $a) { //.... } ``` ### Тип параметра DI [](#тип-параметра-di) Параметр, который создаётся из DI, при этом от входных параметров он не зависит. Создать такой параметр можно указав аттрибут ApiDi. ``` /** * В этом примере входных параметров у апи нет, но при вызове будет создан AuthManager через контейнер. * */ public function test1(#[ApiDI] AuthManager $b) { //.... } ``` ### Тип параметра RequestObject [](#тип-параметра-requestobject) В этом варианте все входные параметры будут представлены в виде параметров одного объекта ``` /** * Все параметры будут преобразованы в параметры объекта AllParamsRequestObject * */ public function test1(#[ApiParams] AllParamsRequestObject $a) { //.... } class AllParamsRequestObject { public string $a; public string $b; public bool $c; } ``` ### Дополнительные возможности для RequestObject и Object [](#дополнительные-возможности-для-requestobject-и-object) #### WithValidation [](#withvalidation) Объекту можно добавить трейт WithValidation, если переопределить методы то можно настроить валидациия для данного объекта. ``` /** Если метод вернёт пустой массив, то валидация будет проигнорирована */ public static function rules(): array { return [ 'date' => ['nullable', 'date:Y-m-d'], ]; } /** * Можно переопределить сообщения об ошибках */ public static function messages(): array { return []; } /** * Можно переопределить атрибуты передаваемые в Validator */ public static function attributes(): array { return []; } ``` #### WithDataMap [](#withdatamap) Объекту можно добавить трейт WithDataMap, если переопределить метод dataMap, то можно управлять созданием объекта. ``` // В случае если трейт подключён, но метод не переопределён, то запустится // стандартное создание объекта, как если бы трейт не был указан public static function dataMap(RouteParam $param, array|object $data): self { return new self($data) } ``` Игнорирование публичных методов контроллеров ============================================ [](#игнорирование-публичных-методов-контроллеров) По умолчанию в схему маршрутизации попадают все публичные методы всех контроллеров, найденных в указанном в конфигурации пространстве имен. Если вам необходимо исключить из маршрутизации часть методов - воспользуйтесь аннотацией `ApiIgnore`: ``` /** * Использование аннотации/атрибута @ApiIgnore для класса исключает все методы класса из маршрутизации * @ApiIgnore */ class ApiController extends BaseController { // ... } ``` Валидация данных ================ [](#валидация-данных) Можно проверить все параметры запроса с помощью объекта запроса. ``` public function testValidation(#[ApiDi] \Tochka\JsonRpc\Support\JsonRpcRequest $request, object $data) { // в validated попадут только те поля для которых указаны правила валидации $validated = $request->validate([ 'object.field' => 'int|string', 'object.field2' => 'required|bool', ]); } ``` Стандартный метод $request->validate при ошибках валидации выбрасывает InvalidParametersException. Если по какой-то причине вы хотите обработать ошибки самостоятельно, можно вызвать validateSilent ``` public function testValidation(#[ApiDi] \Tochka\JsonRpc\Support\JsonRpcRequest $request, object $data) { // В этом случае не будет исключений при провале валидации $validated = $request->validateSilent([ 'object.field' => 'int|string', 'object.field2' => 'required|bool', ]); // получить список ошибок $request->getValidationErrors(); // получить список полей что не прошли валидацию $request->getValidationFailed(); } ``` Как это работает ================ [](#как-это-работает) Клиент посылает валидный JsonRpc2.0-запрос: ``` { "jsonrpc": "2.0", "method": "client_getInfoById", "params": { "clientCode": "100500", "fromAgent" : true }, "id": "service-ab34f8290cfa367dacb" } ``` JsonRpc сервер пытается найти указанный метод `client_getInfoById`. Имя метода разбивается на части: `имяКонтроллера_имяМетода`. Класс контроллера ищется по указанному пространству имен (параметр `jsonrpc.controllerNamespace`) с указанным суффиксом (по умолчанию `Controller`). Для нашего примера сервер попытается подключить класс 'App\\Http\\Controller\\ClientController'. Если контроллер не существует - клиенту вернется ошибка `Method not found`. В найденном контроллере вызывается метод `getInfoById`. Все переданные параметры будут переданы в метод по именам. То есть в контроллере должен быть метод `getInfoById($clientCode, $fromAgent)`. Все параметры будут отвалидированы по типам (если типы указаны). Кроме того, таким способом можно указывать необязательные параметры в методе - в таком случае их необязательно передавать в запросе, вместо непереданных параметров будут использованы значения по умолчанию из метода. Если не будет передан один из обязательных параметров - клиенту вернется ошибка. Несколько вызовов в одном запросе ================================= [](#несколько-вызовов-в-одном-запросе) По спецификации JsonRpc разрешено вызывать несколько методов в одном запросе. Для этого необходимо валидные JsonRpc2.0-вызовы передать в виде массива. Каждый вызываемый метод будет вызван из соответствующего контроллера, а вернувшиеся результаты будут возвращены клиенту в том порядке, в котором пришли запросы. В ответе клиенту всегда присутствует параметр id, если таковой был передан клиентом. Данный параметр также позволяет идентифицировать ответы на свои запросы на стороне клиента. Документация JsonRpc ==================== [](#документация-jsonrpc) Для документирования JsonRpc используется спецификация OpenRpc (). Для генерации OpenRpc-схемы можете использовать совместимый с текущей версией jsonrpc-server пакет [tochka-developers/openrpc](https://github.com/tochka-developers/openrpc) Обновление с v4 до v5 ===================== [](#обновление-с-v4-до-v5) - Если будете использовать tochka-developers/openrpc. Перед установкой убедитесь что версия tochka-developers/jsonrpc-client больше чем 3.11 (в более старых несовместимость с phpdocumentor/reflection-docblock v6) - Удалить из config/jsonrpc строки endpoint, dynamicEndpoint - Если используете атрибут #\[ApiIgnore\], замените на @ApiIgnore (это временное решение для переезда, в дальнейшем методы апи будут указываться явно через #\[ApiMethod\]) - Обновляем версию ``` composer r tochka-developers/jsonrpc:^v5.0 // если испльзуете tochka-developers/openrpc, её тоже нужно обновить composer r tochka-developers/jsonrpc:^v5.0 tochka-developers/openrpc:^v2.0 ``` - Замените вызов сервера ``` // до Route::post('/api/v1/public/jsonrpc', function (Request $request) { return JsonRpcServer::handle($request->getContent(), 'default'); }); // после Route::post('/api/v1/public/jsonrpc', function (Request $request) { $config = ServerConfig::makeFromConfigFile('default'); $server = new JsonRpcServer($config); return $server->handle($request->getContent()); }); ``` - Если стоит tochka-developers/openrpc, обновите его конфигурацию Breaking changes - убрана зависимость bensampo/laravel-enum, если она вам нужна, поставьте самостоятельно, если этот тип объект используется как параметр апи, вам нужно сделать свой PropertyCaster ### Health Score 68 — FairBetter than 99% of packages Maintenance92 Actively maintained with recent releases Popularity40 Moderate usage in the ecosystem Community27 Small or concentrated contributor base Maturity97 Battle-tested with a long release history Bus Factor1 Top contributor holds 50% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~35 days Recently: every ~5 days Total 95 Last Release 43d ago Major Versions v1.1.19b → v2.0.0a2018-05-16 v1.1.20 → v2.0.4a2018-05-21 v2.3.1 → v3.0.0-beta12019-12-18 v3.3.0 → v4.0.0-rc12021-05-17 v4.11.0 → v5.0.0-beta.12026-04-08 PHP version history (8 changes)1.0.0PHP >=5.6.4 v2.0.0aPHP >=7.1.0 v3.0.0PHP >=7.2 v4.0.0-rc1PHP >=7.4 v4.5.0PHP 8.0.\*|8.1.\*|8.2.\* v4.9.0PHP 8.0.\*|8.1.\*|8.2.\*|8.3.\* v4.10.0PHP 8.2.\*|8.3.\*|8.4.\* v4.12.0PHP 8.2.\*|8.3.\*|8.4.\*|8.5.\* ### Community Maintainers ![](https://www.gravatar.com/avatar/d5ec14fdcb7d670c749bdfe547cdcae4dd77a1eb173f01c6787217c8ef90b1d5?d=identicon)[tochka-developers](/maintainers/tochka-developers) ![](https://www.gravatar.com/avatar/dc33cf2a905842e2b7b452bb04d75ba24943d1c22fcffa8aa393d04c0ba20f3c?d=identicon)[darkdarin](/maintainers/darkdarin) --- Top Contributors [![Hatsunyan](https://avatars.githubusercontent.com/u/7223705?v=4)](https://github.com/Hatsunyan "Hatsunyan (14 commits)")[![lexxksb](https://avatars.githubusercontent.com/u/622791?v=4)](https://github.com/lexxksb "lexxksb (7 commits)")[![NBZ4live](https://avatars.githubusercontent.com/u/605126?v=4)](https://github.com/NBZ4live "NBZ4live (2 commits)")[![orlovtech](https://avatars.githubusercontent.com/u/5249166?v=4)](https://github.com/orlovtech "orlovtech (2 commits)")[![Serganbus](https://avatars.githubusercontent.com/u/9009595?v=4)](https://github.com/Serganbus "Serganbus (1 commits)")[![xdloc](https://avatars.githubusercontent.com/u/12979331?v=4)](https://github.com/xdloc "xdloc (1 commits)")[![yekhlakov](https://avatars.githubusercontent.com/u/15815146?v=4)](https://github.com/yekhlakov "yekhlakov (1 commits)") --- Tags jsonrpclaravellaraveljsonrpc ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/tochka-developers-jsonrpc/health.svg) ``` [![Health](https://phpackages.com/badges/tochka-developers-jsonrpc/health.svg)](https://phpackages.com/packages/tochka-developers-jsonrpc) ``` ### Alternatives [laravel/mcp Rapidly build MCP servers for your Laravel applications. 79227.1M230](/packages/laravel-mcp)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 265.2k](/packages/aedart-athenaeum)[larastan/larastan Larastan - Discover bugs in your code without running it. A phpstan/phpstan extension for Laravel 6.5k60.6M10.5k](/packages/larastan-larastan)[psalm/plugin-laravel Psalm plugin for Laravel 3345.4M354](/packages/psalm-plugin-laravel)[illuminate/queue The Illuminate Queue package. 20433.0M1.8k](/packages/illuminate-queue)[mike-bronner/laravel-model-caching Automatic caching for Eloquent models. 2.4k161.4k2](/packages/mike-bronner-laravel-model-caching) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)