microshard / jsonrpcserver
A lightweight JsonRpc Server Bundle for PHP
Requires
- php: ^7.0
- psr/http-message: ~1.0
Requires (Dev)
- php-mock/php-mock: ^2.0
- phpunit/phpunit: ^6.5 || ^7.0
Suggests
- guzzlehttp/guzzle: As a possible implementation of the Psr ServerRequestInterface
- microshard/jsonrpcclient: A client bundle for communication with the JsonRpcServer
This package is not auto-updated.
Last update: 2024-03-17 02:48:08 UTC
README
JsonRpcServer
A lightweight JsonRpc Server Bundle for PHP
Usage
To setup the server you need to create an instance of a Server which requires two parameters. First parameter is a Directory object which holds all request handlers. The second parameter is an authenticator object implementing the Security\AuthenticatorInterface.
$directory = new Directory(); // add handlers to the directory $authenticator = new AllowAllAuthenticator(); $server = new Server($directory, $authenticator);
To run the server and handle any incoming request you just have to pass a valid Psr7 http request that implements the Psr\Http\Message\ServerRequestInterface object. Most Frameworks like Symfony, Laravel or Phalcon already use a compatible Request implementation. Otherwise you can use guzzlehttp/guzzle for an implementation of the ServerRequestInterface.
$request = \GuzzleHttp\Psr7\ServerRequest::fromGlobals(); $server->run($request);
Request Handler
Request handlers have to implement the HandlerInterface which only requires the implementation of one handle(Request $request)
method.
All handlers need to be registered at a Directory for the Server to use it. There are two ways of registering a handler.
Possibility one is to register an existing handler instance.
$handler = new ExampleHandler(); $directory->addHandler('resource', 'method', 1, $handler);
The alternative is to register a callback that creates the handler if it's actually requested, which is the better way so you don't have to create a bunch of handler objects, from which only one is usually used per request.
$directory->addHandlerDefinition('resource', 'method', 1, function(){ return new ExampleHandler(); });
In both cases you have to define 3 additional parameters when registering a handler: resource, method and version. resource and method are simple identifiers which are used in the requests to identify which handler needs to be picked from the Directory to handle the incoming request. The version is an integer which allows you to versionize your handlers if you want/need to. If you don't need it, just put a default 1 in it. If you ever have to change a handler and have multiple clients that send requests to your server, it will come in handy.
Request Format
The request format is very simple and for the most part universal for all requests. As the name indicates, requests are expected to be in json format, an object with the following fields:
Field | Required | Description |
resource | Yes | name of the resource to select the right handler |
method | Yes | name of the method for the resource to select the right handler |
version | No | if the request does not contain a version, the server will use the latest available for the given resource and method |
id | No | a simple identifier that will be send back in the response |
auth | No | authentication data is not required by default, it depends on the Authenticator you want to use in the Server |
payload | No | this is the part where all the data the handler needs to handle the request, should be stored. |
an example could be:
{ "resource": "email", "method": "send", "auth": { "token": "some_auth_token" }, "payload": { "recipient": "some@mail.com", "subject": "some subject", "body": "some message body" } }
Response Format
Like the request format, the response is a json object with the following fields:
Field | Description |
resource | the resource from the request |
method | the method from the request |
version | the version from the request, if non was given it will contain the value latest which is alo a valid value for requests but has the same effect as ommiting the version in the request |
id | the id from the request, if one was given |
status | a http status code - 200 if everything was ok |
message | a response message - OK if everything was ok, otherwise a short info describing the error |
error | this field is only present if the status is not 200. If so, it contains an error code |
payload | the result from the handler which processed the request. |
Client
You don't have to write your own client to communicate with the server, you can use the microshard/jsonrpcclient
bundle.
github