1
1
# 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 )
3
4
[ ![ Code size] ( https://img.shields.io/github/languages/code-size/yoanm/php-jsonrpc-server-sdk.svg )] ( https://github.com/yoanm/php-jsonrpc-server-sdk )
4
5
[ ![ Dependabot Status] ( https://api.dependabot.com/badges/status?host=github\& repo=yoanm/php-jsonrpc-server-sdk )] ( https://dependabot.com )
5
6
@@ -23,16 +24,20 @@ See [yoanm/jsonrpc-server-doc-sdk](https://github.com/yoanm/php-jsonrpc-server-d
23
24
24
25
## How to use
25
26
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
+
30
32
Sdk optionally provide :
31
- - Events dispatch
32
- - Params validation
33
+
34
+ * Events dispatch
35
+ * Params validation
33
36
34
37
### Simple Example
38
+
35
39
#### JSON-RPC Method
40
+
36
41
``` php
37
42
use Yoanm\JsonRpcServer\Domain\JsonRpcMethodInterface;
38
43
@@ -56,8 +61,11 @@ class DummyMethod implements JsonRpcMethodInterface
56
61
}
57
62
}
58
63
```
64
+
59
65
#### Array method resolver (simple example)
66
+
60
67
* 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
+
61
69
``` php
62
70
use Yoanm\JsonRpcServer\Domain\JsonRpcMethodInterface;
63
71
use Yoanm\JsonRpcServer\Domain\JsonRpcMethodResolverInterface;
@@ -89,7 +97,8 @@ class ArrayMethodResolver implements JsonRpcMethodResolverInterface
89
97
}
90
98
```
91
99
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
+
93
102
``` php
94
103
use Yoanm\JsonRpcServer\App\Creator\ResponseCreator;
95
104
use Yoanm\JsonRpcServer\App\Handler\ExceptionHandler;
@@ -119,7 +128,8 @@ $exceptionHandler = new ExceptionHandler($responseCreator);
119
128
$endpoint = new JsonRpcEndpoint($jsonRpcSerializer, $requestHandler, $exceptionHandler);
120
129
```
121
130
122
- Once endpoint is ready, you can send it request string :
131
+ Once endpoint is ready, you can send it request string :
132
+
123
133
``` php
124
134
$requestString = <<<JSONRPC
125
135
{
@@ -132,20 +142,24 @@ JSONRPC;
132
142
$responseString = $endpoint- >index($requestString);
133
143
```
134
144
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
+
146
159
### Events dispatch example
147
160
148
161
#### Simple event dispatcher
162
+
149
163
*You can use [the one used for behat tests](./features/bootstrap/App/BehatRequestLifecycleDispatcher.php) as example*
150
164
151
165
```php
@@ -185,6 +199,7 @@ class SimpleDispatcher implements JsonRpcServerDispatcherInterface
185
199
```
186
200
187
201
Then bind your listeners to your dispatcher:
202
+
188
203
``` php
189
204
use Yoanm\JsonRpcServer\Domain\Event\Acknowledge\OnRequestReceivedEvent;
190
205
use Yoanm\JsonRpcServer\Domain\Event\Acknowledge\OnResponseSendingEvent;
@@ -206,80 +221,88 @@ $dispatcher->addJsonRpcListener(OnMethodSuccessEvent::EVENT_NAME, $listener);
206
221
```
207
222
208
223
And bind dispatcher like following :
224
+
209
225
``` php
210
226
$endpoint->setJsonRpcServerDispatcher($dispatcher);
211
227
$requestHandler->setJsonRpcServerDispatcher($dispatcher);
212
228
$exceptionHandler->setJsonRpcServerDispatcher($dispatcher);
213
229
```
214
230
215
- #### Events dispatched
231
+ #### Events dispatched
216
232
217
233
##### Basic request lifecycle
218
234
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.
244
261
245
262
##### Additional events
246
263
247
264
###### 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
+
256
274
###### Exception
275
+
257
276
` json_rpc_server_skd.on_exception ` / [ ` Action\OnExceptionEvent ` ] ( ./src/Domain/Event/Action/OnExceptionEvent.php )
258
-
277
+
259
278
Dispatched when an exception occurred during sdk execution
260
279
261
280
##### Action vs Acknowledge events
262
281
263
282
###### Acknowledge
283
+
264
284
They have only an acknowledge purpose.
265
285
266
286
They are grouped under ` Yoanm\JsonRpcServer\Domain\Event\Acknowledge ` namespace.
267
287
268
288
###### Action
289
+
269
290
They allow you to override stuffs.
270
291
271
292
They are grouped under ` Yoanm\JsonRpcServer\Domain\Event\Action ` namespace.
272
293
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.
277
299
278
300
### Params validation example
279
301
280
302
* You can use this [ JSON-RPC params symfony validator] ( https://github.com/yoanm/php-jsonrpc-params-symfony-validator-sdk ) as example*
281
303
282
304
To validate params for a given method, do the following :
305
+
283
306
``` php
284
307
use Yoanm\JsonRpcServer\Domain\JsonRpcMethodInterface;
285
308
use Yoanm\JsonRpcServer\Domain\JsonRpcMethodParamsValidatorInterface;
@@ -305,6 +328,7 @@ $requestHandler->setMethodParamsValidator($validator);
305
328
```
306
329
307
330
## Makefile
331
+
308
332
``` bash
309
333
# Install and configure project
310
334
make build
@@ -319,4 +343,5 @@ make behat-coverage
319
343
```
320
344
321
345
## Contributing
346
+
322
347
See [ contributing note] ( ./CONTRIBUTING.md )
0 commit comments