README

???? Updates from Ukrainian Open Source Community

???????? Обращение к гражданам России

Quick How-To

• Install with composer: composer require upgate/laravel-jsonrpc
• In your RouteServiceProvider, do something like this:

// ... use Upgate\LaravelJsonRpc\Contract\ServerInterface as JsonRpcServerContract; class RouteServiceProvider extends ServiceProvider { // ... public function map(Router $router) { $router->group( ['namespace' => $this->namespace], function (Router $router) { // Create an instance of JsonRpcServer $jsonRpcServer = $this->app->make(JsonRpcServerContract::class); // Set default controller namespace $jsonRpcServer->setControllerNamespace($this->namespace); // Register middleware aliases configured for Laravel router $jsonRpcServer->registerMiddlewareAliases($router->getMiddleware()); require app_path('Http/routes.php'); } ); } }

• Use $jsonRpcServer in your routes.php, like this:

$router->post('/jsonrpc', function (Illuminate\Http\Request $request) use ($jsonRpcServer) { $jsonRpcServer->router() ->addMiddlewares(['fooMiddleware', 'barMiddleware', 'auth:rpcGuard']) // Middleware alias names or class names. // Parameters may be specified by separating // the middleware name and parameters with a : ->bindController('foo', 'FooController') // for 'foo.$method' methods invoke FooController->$method(), // for 'foo' method invoke FooConroller->index() ->bind('bar', 'MyController@bar') // for 'bar' method invoke MyController->bar() ->group( ['bazMiddleware'], // add bazMiddleware for methods in this group function ($jsonRpcRouter) { // for 'bar.baz' method invoke MyController->bazz() $jsonRpcRouter->bind('bar.baz', 'MyController@bazz'); } ); // Run json-rpc server with $request passed to middlewares as a handle() method argument return $jsonRpcServer->run($request); });

See ServerTest and RouterTest for more examples.

Exception handling

Descendants of Upgate\LaravelJsonRpc\Exception\JsonRpcException represent JSON-RPC errors according to the spec (see Upgate\LaravelJsonRpc\Server\ErrorCode).

Other exceptions are logged and converted to INTERNAL_ERROR responses by default.

Use Upgate\LaravelJsonRpc\Server\Server::onException() to register custom exception handlers:

use Upgate\LaravelJsonRpc\Server; $jsonRpcServer->onException( SomeExceptionClass::class, function (SomeExceptionClass $e, Server\Request $request = null) { $message = "Some Message"; $code = -32099; return Server\RequestResponse::constructErrorResponse($request ? $request->getId() : null, $message, $code); } ); $jsonRpcServer->onException( \Throwable::class, // catch-all function (\Throwable $e, Server\Request $request = null) { $message = "Some Other Message"; $code = -32098; return Server\RequestResponse::constructErrorResponse($request ? $request->getId() : null, $message, $code); } );

See ServerTest:: testSingleRequestWithExceptionHandler() and ServerTest::testExceptionHandlersPriority() for more examples.

JSON-RPC Request Forms

(since v0.3.0)

Upgate\LaravelJsonRpc\Server\FormRequest is similar to Laravel form requests, but validates JSON-RPC parameters instead.

Example:

use Upgate\LaravelJsonRpc\Server\FormRequest as JsonRpcFormRequest; class MyJsonRpcFormRequest extends JsonRpcFormRequest { public function rules(): array { return [ 'id' => 'required|numeric', 'email' => 'required|email', ]; } } class MyController { public function myAction(MyJsonRpcFormRequest $jsonRpcRequest) { $email = $jsonRpcRequest->email; // or $jsonRpcRequest->get('email'); $allParams = $jsonRpcRequest->all(); // ... } }

If validation fails, the INVALID_PARAMS error response is returned, with validation error details in data.violations.

See the ServerFormRequestTest for more examples.