11# PHP JSON-RPC server sdk
2- [ ![ License] ( https://img.shields.io/github/license/yoanm/symfony-jsonrpc-http-server.svg )] ( https://github.com/yoanm/php-jsonrpc-server-sdk )
2+
3+ [ ![ License] ( https://img.shields.io/github/license/yoanm/php-jsonrpc-server-sdk.svg )] ( https://github.com/yoanm/php-jsonrpc-server-sdk )
34[ ![ Code size] ( https://img.shields.io/github/languages/code-size/yoanm/php-jsonrpc-server-sdk.svg )] ( https://github.com/yoanm/php-jsonrpc-server-sdk )
45[ ![ Dependabot Status] ( https://api.dependabot.com/badges/status?host=github\& repo=yoanm/php-jsonrpc-server-sdk )] ( https://dependabot.com )
56
@@ -23,16 +24,20 @@ See [yoanm/jsonrpc-server-doc-sdk](https://github.com/yoanm/php-jsonrpc-server-d
2324
2425## How to use
2526
26- Sdk requires only two things :
27- - A method resolver : must implements [ JsonRpcMethodResolverInterface] ( ./src/Domain/JsonRpcMethodResolverInterface.php ) , resolving logic's is your own.
28- - Methods : JsonRpc methods which implements [ JsonRpcMethodInterface] ( ./src/Domain/JsonRpcMethodInterface.php )
29-
27+ Sdk requires only two things :
28+
29+ * A method resolver : must implements [ JsonRpcMethodResolverInterface] ( ./src/Domain/JsonRpcMethodResolverInterface.php ) , resolving logic's is your own.
30+ * Methods : JsonRpc methods which implements [ JsonRpcMethodInterface] ( ./src/Domain/JsonRpcMethodInterface.php )
31+
3032Sdk optionally provide :
31- - Events dispatch
32- - Params validation
33+
34+ * Events dispatch
35+ * Params validation
3336
3437### Simple Example
38+
3539#### JSON-RPC Method
40+
3641``` php
3742use Yoanm\JsonRpcServer\Domain\JsonRpcMethodInterface;
3843
@@ -56,8 +61,11 @@ class DummyMethod implements JsonRpcMethodInterface
5661 }
5762}
5863```
64+
5965#### Array method resolver (simple example)
66+
6067* You can use [ the one used for behat tests] ( ./features/bootstrap/App/BehatMethodResolver.php ) or this [ Psr11 method resolver] ( https://github.com/yoanm/php-jsonrpc-server-sdk-psr11-resolver ) as example*
68+
6169``` php
6270use Yoanm\JsonRpcServer\Domain\JsonRpcMethodInterface;
6371use Yoanm\JsonRpcServer\Domain\JsonRpcMethodResolverInterface;
@@ -89,7 +97,8 @@ class ArrayMethodResolver implements JsonRpcMethodResolverInterface
8997}
9098```
9199
92- Then add your method to the resolver and create the endpoint :
100+ Then add your method to the resolver and create the endpoint :
101+
93102``` php
94103use Yoanm\JsonRpcServer\App\Creator\ResponseCreator;
95104use Yoanm\JsonRpcServer\App\Handler\ExceptionHandler;
@@ -119,7 +128,8 @@ $exceptionHandler = new ExceptionHandler($responseCreator);
119128$endpoint = new JsonRpcEndpoint($jsonRpcSerializer, $requestHandler, $exceptionHandler);
120129```
121130
122- Once endpoint is ready, you can send it request string :
131+ Once endpoint is ready, you can send it request string :
132+
123133``` php
124134$requestString = <<<JSONRPC
125135{
@@ -132,20 +142,24 @@ JSONRPC;
132142$responseString = $endpoint- >index($requestString);
133143```
134144
135- ` $responseString ` will be the following string depending of method returned value :
136- * ``` json
137- {"jsonrpc" :" 2.0" ,"id" :1 ,"result" :{"status" :" done" }}
138- ```
139- * ``` json
140- {"jsonrpc" :" 2.0" ,"id" :1 ,"result" :null }
141- ```
142-
143- * ``` json
144- {"jsonrpc" :" 2.0" ,"id" :1 ,"result" :12345 }
145- ```
145+ ` $responseString ` will be the following string depending of method returned value :
146+
147+ * ``` json
148+ {"jsonrpc" :" 2.0" ,"id" :1 ,"result" :{"status" :" done" }}
149+ ```
150+
151+ * ```json
152+ {"jsonrpc" :" 2.0" ,"id" :1 ,"result" :null }
153+ ```
154+
155+ * ```json
156+ {"jsonrpc" :" 2.0" ,"id" :1 ,"result" :12345 }
157+ ```
158+
146159### Events dispatch example
147160
148161#### Simple event dispatcher
162+
149163*You can use [the one used for behat tests](./features/bootstrap/App/BehatRequestLifecycleDispatcher.php) as example*
150164
151165```php
@@ -185,6 +199,7 @@ class SimpleDispatcher implements JsonRpcServerDispatcherInterface
185199```
186200
187201Then bind your listeners to your dispatcher:
202+
188203``` php
189204use Yoanm\JsonRpcServer\Domain\Event\Acknowledge\OnRequestReceivedEvent;
190205use Yoanm\JsonRpcServer\Domain\Event\Acknowledge\OnResponseSendingEvent;
@@ -206,80 +221,88 @@ $dispatcher->addJsonRpcListener(OnMethodSuccessEvent::EVENT_NAME, $listener);
206221```
207222
208223And bind dispatcher like following :
224+
209225``` php
210226$endpoint->setJsonRpcServerDispatcher($dispatcher);
211227$requestHandler->setJsonRpcServerDispatcher($dispatcher);
212228$exceptionHandler->setJsonRpcServerDispatcher($dispatcher);
213229```
214230
215- #### Events dispatched
231+ #### Events dispatched
216232
217233##### Basic request lifecycle
218234
219- - ` json_rpc_server_skd.on_request_received ` / [ ` Acknowledge\OnRequestReceivedEvent ` ] ( ./src/Domain/Event/Acknowledge/OnRequestReceivedEvent.php )
220-
221- Dispatched when a request has been passed to the endpoint and successfully deserialized.
222-
223- > N.B. : Lonely cases where this event is not dispatched are when the request string is not a valid JSON-RPC request.
224- >
225- > It include :
226- > - Parse error exception (malformed json string)
227- > - For simple request only, in case of Invalid request (not an object / missing required properties / ...).
228- >
229- > * :warning : For batch request containing Invalid SubRequest, this event will still be dispatched*
230-
231- - Either
232-
233- - ` json_rpc_server_skd.on_method_success ` / [ ` Action\OnMethodSuccessEvent ` ] ( ./src/Domain/Event/Action/OnMethodSuccessEvent.php )
234-
235- Dispatched ** only in case JSON-RPC method has been successfully executed** .
236-
237- - ` json_rpc_server_skd.on_method_failure ` / [ ` Action\OnMethodFailureEvent ` ] ( ./src/Domain/Event/Action/OnMethodFailureEvent.php )
238-
239- Dispatched ** only in case JSON-RPC method throw an exception during execution** .
240-
241- - ` json_rpc_server_skd.on_response_sending ` / [ ` Acknowledge\OnResponseSendingEvent ` ] ( ./src/Domain/Event/Acknowledge/OnResponseSendingEvent.php )
242-
243- Dispatched when a response has been successfully serialized by the endpoint and will be returned.
235+ * ` json_rpc_server_skd.on_request_received ` / [ ` Acknowledge\OnRequestReceivedEvent ` ] ( ./src/Domain/Event/Acknowledge/OnRequestReceivedEvent.php )
236+
237+ Dispatched when a request has been passed to the endpoint and successfully deserialized.
238+
239+ > N.B. : Lonely cases where this event is not dispatched are when the request string is not a valid JSON-RPC request.
240+ >
241+ > It include :
242+ >
243+ > * Parse error exception (malformed json string)
244+ > * For simple request only, in case of Invalid request (not an object / missing required properties / ...).
245+ >
246+ > *:warning: For batch request containing Invalid SubRequest, this event will still be dispatched*
247+
248+ * Either
249+
250+ * ` json_rpc_server_skd.on_method_success ` / [ ` Action\OnMethodSuccessEvent ` ] ( ./src/Domain/Event/Action/OnMethodSuccessEvent.php )
251+
252+ Dispatched ** only in case JSON-RPC method has been successfully executed** .
253+
254+ * ` json_rpc_server_skd.on_method_failure ` / [ ` Action\OnMethodFailureEvent ` ] ( ./src/Domain/Event/Action/OnMethodFailureEvent.php )
255+
256+ Dispatched ** only in case JSON-RPC method throw an exception during execution** .
257+
258+ * ` json_rpc_server_skd.on_response_sending ` / [ ` Acknowledge\OnResponseSendingEvent ` ] ( ./src/Domain/Event/Acknowledge/OnResponseSendingEvent.php )
259+
260+ Dispatched when a response has been successfully serialized by the endpoint and will be returned.
244261
245262##### Additional events
246263
247264###### Batch request
248- - ` json_rpc_server_skd.on_batch_sub_request_processing ` / [ ` Acknowledge\OnBatchSubRequestProcessingEvent ` ] ( ./src/Domain/Event/Acknowledge/OnBatchSubRequestProcessingEvent.php )
249-
250- Dispatched before that a sub request will be processed.
251-
252- - ` json_rpc_server_skd.on_batch_sub_request_processed ` / [ ` Acknowledge\OnBatchSubRequestProcessedEvent ` ] ( ./src/Domain/Event/Acknowledge/OnBatchSubRequestProcessedEvent.php )
253-
254- Dispatched after that a sub request has been processed (regardless of the success or failure of the sub request method execution).
255-
265+
266+ * ` json_rpc_server_skd.on_batch_sub_request_processing ` / [ ` Acknowledge\OnBatchSubRequestProcessingEvent ` ] ( ./src/Domain/Event/Acknowledge/OnBatchSubRequestProcessingEvent.php )
267+
268+ Dispatched before that a sub request will be processed.
269+
270+ * ` json_rpc_server_skd.on_batch_sub_request_processed ` / [ ` Acknowledge\OnBatchSubRequestProcessedEvent ` ] ( ./src/Domain/Event/Acknowledge/OnBatchSubRequestProcessedEvent.php )
271+
272+ Dispatched after that a sub request has been processed (regardless of the success or failure of the sub request method execution).
273+
256274###### Exception
275+
257276` json_rpc_server_skd.on_exception ` / [ ` Action\OnExceptionEvent ` ] ( ./src/Domain/Event/Action/OnExceptionEvent.php )
258-
277+
259278Dispatched when an exception occurred during sdk execution
260279
261280##### Action vs Acknowledge events
262281
263282###### Acknowledge
283+
264284They have only an acknowledge purpose.
265285
266286They are grouped under ` Yoanm\JsonRpcServer\Domain\Event\Acknowledge ` namespace.
267287
268288###### Action
289+
269290They allow you to override stuffs.
270291
271292They are grouped under ` Yoanm\JsonRpcServer\Domain\Event\Action ` namespace.
272293
273- Here, the list :
274- - [ ` Action\OnMethodSuccessEvent ` ] ( ./src/Domain/Event/Action/OnMethodSuccessEvent.php ) allow you to update/change the result of the method.
275- - [ ` Action\OnMethodFailureEvent ` ] ( ./src/Domain/Event/Action/OnMethodFailureEvent.php ) allow you to update/change the exception thrown by the method.
276- - [ ` Action\OnExceptionEvent ` ] ( ./src/Domain/Event/Action/OnExceptionEvent.php ) allow you to update/change the exception thrown.
294+ Here, the list :
295+
296+ * [ ` Action\OnMethodSuccessEvent ` ] ( ./src/Domain/Event/Action/OnMethodSuccessEvent.php ) allow you to update/change the result of the method.
297+ * [ ` Action\OnMethodFailureEvent ` ] ( ./src/Domain/Event/Action/OnMethodFailureEvent.php ) allow you to update/change the exception thrown by the method.
298+ * [ ` Action\OnExceptionEvent ` ] ( ./src/Domain/Event/Action/OnExceptionEvent.php ) allow you to update/change the exception thrown.
277299
278300### Params validation example
279301
280302* You can use this [ JSON-RPC params symfony validator] ( https://github.com/yoanm/php-jsonrpc-params-symfony-validator-sdk ) as example*
281303
282304To validate params for a given method, do the following :
305+
283306``` php
284307use Yoanm\JsonRpcServer\Domain\JsonRpcMethodInterface;
285308use Yoanm\JsonRpcServer\Domain\JsonRpcMethodParamsValidatorInterface;
@@ -305,6 +328,7 @@ $requestHandler->setMethodParamsValidator($validator);
305328```
306329
307330## Makefile
331+
308332``` bash
309333# Install and configure project
310334make build
@@ -319,4 +343,5 @@ make behat-coverage
319343```
320344
321345## Contributing
346+
322347See [ contributing note] ( ./CONTRIBUTING.md )
0 commit comments