tochka-developers / jsonrpc-client
JsonRpc Client for Laravel
Installs: 14 623
Dependents: 0
Suggesters: 0
Security: 0
Stars: 7
Watchers: 5
Forks: 11
Open Issues: 0
Requires
- php: ^8.0|^8.1|^8.2|^8.3
- ext-json: *
- illuminate/cache: ^9.0|^10.0|^11.0
- illuminate/config: ^9.0|^10.0|^11.0
- illuminate/console: ^9.0|^10.0|^11.0
- illuminate/container: ^9.0|^10.0|^11.0
- illuminate/log: ^9.0|^10.0|^11.0
- illuminate/pipeline: ^9.0|^10.0|^11.0
- illuminate/support: ^9.0|^10.0|^11.0
- php-http/discovery: ^1.15
- psr/http-client: ^1.0
- psr/http-client-implementation: 1.0
- psr/http-factory: ^1.0
- psr/http-factory-implementation: 1.0
- tochka-developers/jsonrpc-annotations: ^1.3
- tochka-developers/jsonrpc-standard: ^1.4
Requires (Dev)
- bensampo/laravel-enum: ^5.0
- laravel/pint: ^1.4
- mockery/mockery: ^1.0
- orchestra/testbench: ^7.1
- php-http/mock-client: ^1.5
- phpunit/phpunit: ^9.6
- roave/security-advisories: dev-latest
- timacdonald/log-fake: ^2.0
- vimeo/psalm: ^5.6
- dev-master
- v5.0.x-dev
- v3.x-dev
- v3.8.0
- v3.7.1
- v3.7.0
- v3.6.0
- v3.5.1
- v3.5.0
- v3.4.1
- v3.4.0
- v3.3.4
- v3.3.3
- v3.3.2
- v3.3.1
- v3.3.0
- v3.2.2
- v3.2.1
- v3.2.0
- v3.0.1
- v3.0.0
- v3.0.0-beta4
- v3.0.0-beta3
- v3.0.0-beta2
- v3.0.0-beta1
- v2.2.0
- v2.1.0
- v2.0.0
- v2.0.0-beta3
- v2.0.0-beta2
- v2.0.0-beta1
- v1.1.4
- v1.1.3
- v1.1.2
- v1.1.1
- v1.1.0
- v1.0.7
- v1.0.6
- v1.0.5
- v1.0.4
- v1.0.3
- v1.0.2
- v1.0.1
- v1.0.0
This package is auto-updated.
Last update: 2024-10-28 07:10:01 UTC
README
Описание
JsonRpc клиент - реализация клиента для JsonRpc-сервера. Работает по спецификации JsonRpc 2.0. Протестирован и работает с оригинальным сервером JsonRpc от Tochka.
Установка
Laravel
composer require tochka-developers/jsonrpc-client
- Опубликуйте конфигурацию:
php artisan vendor:publish --provider="Tochka\JsonRpcClient\JsonRpcClientServiceProvider"
Lumen
composer require tochka-developers/jsonrpc-client
- Скопируйте конфигурацию из пакета (
vendor/tochka-developers/jsonrpc/config/jsonrpc-client.php
) в проект (config/jsonrpc-client.php
) - Подключите конфигурацию в
bootstrap/app.php
:
$app->configure('jsonrpc-client');
- Включите поддержку фасадов в
bootstrap/app.php
:
$app->withFacades();
- Если планируете использовать автоматическую генерацию прокси-клиента - зарегистрируйте сервис-провайдер
Tochka\JsonRpcClient\JsonRpcClientServiceProvider
вbootstrap/app.php
:
$app->register(Tochka\JsonRpcClient\JsonRpcClientServiceProvider::class);
Использование
Настройка
Конфигурация находится в файле app/jsonrpc-client.php
.
В данном файле прописываются настройки для всех JsonRpc-подключений.
clientName
- Имя клиента. Данное имя будет подставляться в ID-всех запросов в виде префикса. Позволяет идентифицировать сервис.default
- подключение по умолчанию. Должно содержать имя подключения.connections
- массив подключений. Каждое подключение должно иметь уникальный ключ (название подключения).
Настройки подключений:
url
- URL-адрес (или IP) для подключения к JsonRpc-серверу. Должен содержать полный путь к точке входа (например: https://api.jsonrpc.com/v1/jsonrpc).clientClass
- класс, который используется в качестве прокси-класса. Необходимо указывать полное наименование (с пространством имен). Используется при автоматической генерации прокси-класса.extendedStubs
- генерация расширенного описания АПИ в виде классов-хелперов для входных и выходных параметров методовoptions
- массив опций подключения (см. https://docs.guzzlephp.org/en/stable/request-options.html)middleware
- список классов-middleware, которые подготавливают запрос перед отправкой. Возможно перечисление классов-middleware в виде элементов массива, либо, если необходимо передать в класс дополнительные параметры - в качестве ключей массива указываются классы-middleware, в качестве значения - массив с параметрами.
В пакете доступно две middleware:
AuthTokenMiddleware
- класс авторизации по токену в заголовке. Параметры:name
- имя заголовка,value
- значение токенаAuthBasicMiddleware
- класс Basic-авторизации. Параметры:scheme
- тип авторизации (basic
,digest
,ntlm
),username
иpassword
- данные для авторизацииAdditionalHeadersMiddleware
- класс для добавления кастомных заголовков. Параметры:headers
- ассоциативный массив с заголовками, где ключ - имя заголовка, а значение - значение заголовка.
Генерация прокси-класса
Прокси-класс - это фасад JsonRpcClient, который содержит информацию обо всех доступных методах JsonRpc-сервера, а также сам делает маппинг параметров, переданных в метод, в виде ассоциативного массива. Если сервер умеет возвращать SMD-схему, то такой класс может быть сгенерирован автоматически.
Для генерации класса воспользуйтесь командой:
php artisan jsonrpc:generateClient connection
Для успешной генерации должно выполняться несколько условий:
- JsonRpc-сервер должен поддерживать возврат SMD-схемы (при передаче GET-параметра ?smd)
- Желательно, чтобы в качестве сервера использовался
tochka-developers/jsonrpc
. Данный пакет умеет возвращать расширенную информацию для более точной генерации прокси-класса - Должен быть прописан URL-адрес JsonRpc-сервера
- Должно быть указано полное имя прокси-класса. Путь к файлу класса будет сгенерирован автоматически исходя из
пространства имен и настроек
composer
. - Папка, в которой будет находиться прокси-класс, должна иметь иметь права на запись.
Если все указанные условия выполняются - то будет создан прокси-класс на указанное соединение. Для обновления прокси-класса (в случае обновления методов сервера) - повторно вызовите указанную команду. Если необходимо сгенерировать классы для всех указанных соединений - вызовите указанную команду без указания соединения:
php artisan jsonrpc:generateClient
Вызовы методов
Вызов метода JsonRpc:
//.... $result = Api::fooBar('Some text');
Клиент поддерживает вызов нескольких удаленных методов через один запрос:
$api = Api::batch(); $api->foo('params'); $api->bar(123); $api->someMethod(1, true); [$resultFoo, $resultBar, $resultSome] = $api->execute();
Клиент поддерживает кеширование результатов с помощью метода cache
:
$result = Api::cache(10)->fooBar('Some text');
При таком вызове результаты будут закешированы на 10 минут, и последующих вызовах этого метода с такими же параметрами - запрос на сервер не будет посылаться, результат будет сразу получаться из кеша. Естественно, результаты кешируются только для успешных вызовов.
Также кеширование поддерживается и для нескольких вызовов:
$api = Api::batch(); $resultFoo = $api->cache(10)->foo('params'); $resultBar = $api->bar(123); $resultSome = $api->cache(60)->someMethod(1, true); [$resultFoo, $resultBar, $resultSome] = $api->execute();
Учтите, что кешироваться будет только тот метод, перед которым был вызван cache
.
Middleware
Классы-middleware позволяет внести изменения в исходящие запросы, например добавить дополнительные заголовки, включить авторизацию, либо внести изменения в само тело запроса.
Вы можете использовать свои классы, указав их имена в конфигурации необходимого подключения. Есть два типа middleware. Первый рассчитан на взаимодействие с каждым конкретным JsonRpc-запросом, даже если они запущены в batch-режиме. Второй тип запускается один раз на весь транспортный запрос.
Первый тип middleware запускается для каждого вызова метода в рамках одного запроса на сервер. То есть, если был сделан batch-запрос с вызовами 3х методов - каждая такая middleware будет запущена по одному разу для каждого вызванного метода.
Второй тип middleware будет запущен только один раз для всего запроса, и в него будет передан весь стек вызовов. Второй тип подходит для middleware, занимающихся добавлением кас томных заголовков, авторизации и прочих модификаций транспортного запроса.
В классе middleware должне быть реализован один метод - handle
.
Первые два параметра обязательные.
Пример middleware для обработки каждого вызова в запросе (первый тип):
class SomeMiddleware { public function handle(\Tochka\JsonRpcClient\Request $request, \Closure $next): void { // ... return $next($request); } }
Пример middleware для обработки всего запроса целиком:
class SomeMiddleware implements \Tochka\JsonRpcClient\Contracts\OnceExecutedMiddleware { /** * @param \Tochka\JsonRpcClient\Standard\JsonRpcRequest[] $requests * @param \Closure $next */ public function handle(array $requests, \Closure $next): void { // ... return $next($requests); } }
Чтобы продолжить выполнение цепочки middleware, в методе необходимо обязательно вызвать метод $next, передав туда
актуальную версию $request.
Кроме того, вы можете в параметрах метода handle
использовать:
- дополнительные параметры, передаваемые в конфигурации:
// config 'middleware' => [ \Tochka\JsonRpcClient\Middleware\AuthTokenMiddleware::class => [ 'name' => 'X-Access-Key', 'value' => 'TokenValue', ], ] // middleware use Tochka\JsonRpcClient\Request; class AuthTokenMiddleware implements \Tochka\JsonRpcClient\Contracts\OnceExecutedMiddleware { public function handle(array $request, \Closure $next, $value, $name = 'X-Access-Key') { // ... return $next($request); } }
Порядок указание параметров не важен, указанные в конфигурации значения будут переданы в middleware по имени параметра.
- контекстные классы
Tochka\JsonRpcClient\Contracts\TransportClient
иTochka\JsonRpcClient\ClientConfig
. Если у параметра указать один из указанных типов, то в метод при вызове будут переданы текущие экземпляры классов, отвечающих за формирование транспортного запроса (например, сконфигурированный экземпляр классаTochka\JsonRpcClient\Client\HttpClient
) либо класс с конфигурацией текущего соединения. - любой другой класс/контракт/фасад, зарегистрированный в DI Laravel
[]: https://docs.guzzlephp.org/en/stable/request-options.html(описание