From ddaf53e3e4fef0a85e9f787f2afbe607053ac875 Mon Sep 17 00:00:00 2001 From: Yoanm Date: Sun, 2 Apr 2023 15:24:09 +0200 Subject: [PATCH] Miscelaneous fixes --- .gitattributes | 4 ++ .remarkignore | 1 + .remarkrc | 6 +++ README.md | 143 +++++++++++++++++++++++++++++-------------------- composer.json | 2 +- 5 files changed, 96 insertions(+), 60 deletions(-) create mode 100644 .remarkignore create mode 100644 .remarkrc diff --git a/.gitattributes b/.gitattributes index 67ae0235..500a7cf5 100644 --- a/.gitattributes +++ b/.gitattributes @@ -4,6 +4,10 @@ /.gitignore export-ignore /.scrutinizer.yml export-ignore /.travis.yml export-ignore +/.editorconfig export-ignore +/codecov.yml export-ignore +/.remarkrc export-ignore +/.remarkignore export-ignore /behat.yml export-ignore /phpunit.xml.dist export-ignore /phpcs.xml.dist export-ignore diff --git a/.remarkignore b/.remarkignore new file mode 100644 index 00000000..22d0d82f --- /dev/null +++ b/.remarkignore @@ -0,0 +1 @@ +vendor diff --git a/.remarkrc b/.remarkrc new file mode 100644 index 00000000..0527df56 --- /dev/null +++ b/.remarkrc @@ -0,0 +1,6 @@ +{ + "plugins": [ + "remark-preset-lint-consistent", + "remark-preset-lint-recommended" + ] +} diff --git a/README.md b/README.md index 50ee6bd5..ff48a560 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,6 @@ # PHP JSON-RPC server sdk -[![License](https://img.shields.io/github/license/yoanm/symfony-jsonrpc-http-server.svg)](https://github.com/yoanm/php-jsonrpc-server-sdk) + +[![License](https://img.shields.io/github/license/yoanm/php-jsonrpc-server-sdk.svg)](https://github.com/yoanm/php-jsonrpc-server-sdk) [![Code size](https://img.shields.io/github/languages/code-size/yoanm/php-jsonrpc-server-sdk.svg)](https://github.com/yoanm/php-jsonrpc-server-sdk) [![Dependabot Status](https://api.dependabot.com/badges/status?host=github\&repo=yoanm/php-jsonrpc-server-sdk)](https://dependabot.com) @@ -23,16 +24,20 @@ See [yoanm/jsonrpc-server-doc-sdk](https://github.com/yoanm/php-jsonrpc-server-d ## How to use -Sdk requires only two things : - - A method resolver : must implements [JsonRpcMethodResolverInterface](./src/Domain/JsonRpcMethodResolverInterface.php), resolving logic's is your own. - - Methods : JsonRpc methods which implements [JsonRpcMethodInterface](./src/Domain/JsonRpcMethodInterface.php) - +Sdk requires only two things : + +* A method resolver : must implements [JsonRpcMethodResolverInterface](./src/Domain/JsonRpcMethodResolverInterface.php), resolving logic's is your own. +* Methods : JsonRpc methods which implements [JsonRpcMethodInterface](./src/Domain/JsonRpcMethodInterface.php) + Sdk optionally provide : - - Events dispatch - - Params validation + +* Events dispatch +* Params validation ### Simple Example + #### JSON-RPC Method + ```php use Yoanm\JsonRpcServer\Domain\JsonRpcMethodInterface; @@ -56,8 +61,11 @@ class DummyMethod implements JsonRpcMethodInterface } } ``` + #### Array method resolver (simple example) + *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* + ```php use Yoanm\JsonRpcServer\Domain\JsonRpcMethodInterface; use Yoanm\JsonRpcServer\Domain\JsonRpcMethodResolverInterface; @@ -89,7 +97,8 @@ class ArrayMethodResolver implements JsonRpcMethodResolverInterface } ``` -Then add your method to the resolver and create the endpoint : +Then add your method to the resolver and create the endpoint : + ```php use Yoanm\JsonRpcServer\App\Creator\ResponseCreator; use Yoanm\JsonRpcServer\App\Handler\ExceptionHandler; @@ -119,7 +128,8 @@ $exceptionHandler = new ExceptionHandler($responseCreator); $endpoint = new JsonRpcEndpoint($jsonRpcSerializer, $requestHandler, $exceptionHandler); ``` -Once endpoint is ready, you can send it request string : +Once endpoint is ready, you can send it request string : + ```php $requestString = <<index($requestString); ``` -`$responseString` will be the following string depending of method returned value : - * ```json - {"jsonrpc":"2.0","id":1,"result":{"status":"done"}} - ``` - * ```json - {"jsonrpc":"2.0","id":1,"result":null} - ``` - - * ```json - {"jsonrpc":"2.0","id":1,"result":12345} - ``` +`$responseString` will be the following string depending of method returned value : + +* ```json + {"jsonrpc":"2.0","id":1,"result":{"status":"done"}} + ``` + +* ```json + {"jsonrpc":"2.0","id":1,"result":null} + ``` + +* ```json + {"jsonrpc":"2.0","id":1,"result":12345} + ``` + ### Events dispatch example #### Simple event dispatcher + *You can use [the one used for behat tests](./features/bootstrap/App/BehatRequestLifecycleDispatcher.php) as example* ```php @@ -185,6 +199,7 @@ class SimpleDispatcher implements JsonRpcServerDispatcherInterface ``` Then bind your listeners to your dispatcher: + ```php use Yoanm\JsonRpcServer\Domain\Event\Acknowledge\OnRequestReceivedEvent; use Yoanm\JsonRpcServer\Domain\Event\Acknowledge\OnResponseSendingEvent; @@ -206,80 +221,88 @@ $dispatcher->addJsonRpcListener(OnMethodSuccessEvent::EVENT_NAME, $listener); ``` And bind dispatcher like following : + ```php $endpoint->setJsonRpcServerDispatcher($dispatcher); $requestHandler->setJsonRpcServerDispatcher($dispatcher); $exceptionHandler->setJsonRpcServerDispatcher($dispatcher); ``` -#### Events dispatched +#### Events dispatched ##### Basic request lifecycle - - `json_rpc_server_skd.on_request_received` / [`Acknowledge\OnRequestReceivedEvent`](./src/Domain/Event/Acknowledge/OnRequestReceivedEvent.php) - - Dispatched when a request has been passed to the endpoint and successfully deserialized. - - > N.B. : Lonely cases where this event is not dispatched are when the request string is not a valid JSON-RPC request. - > - > It include : - > - Parse error exception (malformed json string) - > - For simple request only, in case of Invalid request (not an object / missing required properties / ...). - > - > *:warning: For batch request containing Invalid SubRequest, this event will still be dispatched* - - - Either - - - `json_rpc_server_skd.on_method_success` / [`Action\OnMethodSuccessEvent`](./src/Domain/Event/Action/OnMethodSuccessEvent.php) - - Dispatched **only in case JSON-RPC method has been successfully executed**. - - - `json_rpc_server_skd.on_method_failure` / [`Action\OnMethodFailureEvent`](./src/Domain/Event/Action/OnMethodFailureEvent.php) - - Dispatched **only in case JSON-RPC method throw an exception during execution**. - - - `json_rpc_server_skd.on_response_sending` / [`Acknowledge\OnResponseSendingEvent`](./src/Domain/Event/Acknowledge/OnResponseSendingEvent.php) - - Dispatched when a response has been successfully serialized by the endpoint and will be returned. +* `json_rpc_server_skd.on_request_received` / [`Acknowledge\OnRequestReceivedEvent`](./src/Domain/Event/Acknowledge/OnRequestReceivedEvent.php) + + Dispatched when a request has been passed to the endpoint and successfully deserialized. + + > N.B. : Lonely cases where this event is not dispatched are when the request string is not a valid JSON-RPC request. + > + > It include : + > + > * Parse error exception (malformed json string) + > * For simple request only, in case of Invalid request (not an object / missing required properties / ...). + > + > *:warning: For batch request containing Invalid SubRequest, this event will still be dispatched* + +* Either + + * `json_rpc_server_skd.on_method_success` / [`Action\OnMethodSuccessEvent`](./src/Domain/Event/Action/OnMethodSuccessEvent.php) + + Dispatched **only in case JSON-RPC method has been successfully executed**. + + * `json_rpc_server_skd.on_method_failure` / [`Action\OnMethodFailureEvent`](./src/Domain/Event/Action/OnMethodFailureEvent.php) + + Dispatched **only in case JSON-RPC method throw an exception during execution**. + +* `json_rpc_server_skd.on_response_sending` / [`Acknowledge\OnResponseSendingEvent`](./src/Domain/Event/Acknowledge/OnResponseSendingEvent.php) + + Dispatched when a response has been successfully serialized by the endpoint and will be returned. ##### Additional events ###### Batch request -- `json_rpc_server_skd.on_batch_sub_request_processing` / [`Acknowledge\OnBatchSubRequestProcessingEvent`](./src/Domain/Event/Acknowledge/OnBatchSubRequestProcessingEvent.php) - - Dispatched before that a sub request will be processed. - - - `json_rpc_server_skd.on_batch_sub_request_processed` / [`Acknowledge\OnBatchSubRequestProcessedEvent`](./src/Domain/Event/Acknowledge/OnBatchSubRequestProcessedEvent.php) - - Dispatched after that a sub request has been processed (regardless of the success or failure of the sub request method execution). - + +* `json_rpc_server_skd.on_batch_sub_request_processing` / [`Acknowledge\OnBatchSubRequestProcessingEvent`](./src/Domain/Event/Acknowledge/OnBatchSubRequestProcessingEvent.php) + + Dispatched before that a sub request will be processed. + +* `json_rpc_server_skd.on_batch_sub_request_processed` / [`Acknowledge\OnBatchSubRequestProcessedEvent`](./src/Domain/Event/Acknowledge/OnBatchSubRequestProcessedEvent.php) + + Dispatched after that a sub request has been processed (regardless of the success or failure of the sub request method execution). + ###### Exception + `json_rpc_server_skd.on_exception` / [`Action\OnExceptionEvent`](./src/Domain/Event/Action/OnExceptionEvent.php) - + Dispatched when an exception occurred during sdk execution ##### Action vs Acknowledge events ###### Acknowledge + They have only an acknowledge purpose. They are grouped under `Yoanm\JsonRpcServer\Domain\Event\Acknowledge` namespace. ###### Action + They allow you to override stuffs. They are grouped under `Yoanm\JsonRpcServer\Domain\Event\Action` namespace. -Here, the list : - - [`Action\OnMethodSuccessEvent`](./src/Domain/Event/Action/OnMethodSuccessEvent.php) allow you to update/change the result of the method. - - [`Action\OnMethodFailureEvent`](./src/Domain/Event/Action/OnMethodFailureEvent.php) allow you to update/change the exception thrown by the method. - - [`Action\OnExceptionEvent`](./src/Domain/Event/Action/OnExceptionEvent.php) allow you to update/change the exception thrown. +Here, the list : + +* [`Action\OnMethodSuccessEvent`](./src/Domain/Event/Action/OnMethodSuccessEvent.php) allow you to update/change the result of the method. +* [`Action\OnMethodFailureEvent`](./src/Domain/Event/Action/OnMethodFailureEvent.php) allow you to update/change the exception thrown by the method. +* [`Action\OnExceptionEvent`](./src/Domain/Event/Action/OnExceptionEvent.php) allow you to update/change the exception thrown. ### Params validation example *You can use this [JSON-RPC params symfony validator](https://github.com/yoanm/php-jsonrpc-params-symfony-validator-sdk) as example* To validate params for a given method, do the following : + ```php use Yoanm\JsonRpcServer\Domain\JsonRpcMethodInterface; use Yoanm\JsonRpcServer\Domain\JsonRpcMethodParamsValidatorInterface; @@ -305,6 +328,7 @@ $requestHandler->setMethodParamsValidator($validator); ``` ## Makefile + ```bash # Install and configure project make build @@ -319,4 +343,5 @@ make behat-coverage ``` ## Contributing + See [contributing note](./CONTRIBUTING.md) diff --git a/composer.json b/composer.json index 10ccbf52..68543ee1 100644 --- a/composer.json +++ b/composer.json @@ -35,7 +35,7 @@ "ext-json": "*" }, "require-dev": { - "behat/behat": "~3.0", + "behat/behat": "^3.9.0", "dvdoug/behat-code-coverage": "^5.0", "phpspec/prophecy": "^1.15", "phpspec/prophecy-phpunit": "^2.0",