Merge pull request #16 from scaytrase/feature/readme

README

Author: scaytrase

JsonRpc/ResponseBodyValidator.php

@@ -44,7 +44,6 @@ public function validate(\stdClass $response)
             if (!property_exists($response->{JsonRpcResponseInterface::ERROR_FIELD}, JsonRpcErrorInterface::ERROR_MESSAGE_FIELD)) {
                 throw ResponseParseException::noErrorMessagePresent();
             }
-
         }
     }
 }

JsonRpc/Tests/AbstractJsonRpcClientTest.php

@@ -7,11 +7,12 @@
 use GuzzleHttp\Exception\GuzzleException;
 use GuzzleHttp\HandlerStack;
 use GuzzleHttp\Psr7\Response;
+use PHPUnit\Framework\TestCase;
 use ScayTrase\Api\JsonRpc\JsonRpcNotification;
 use ScayTrase\Api\JsonRpc\JsonRpcRequest;
 use ScayTrase\Api\Rpc\RpcErrorInterface;
 
-abstract class AbstractJsonRpcClientTest extends \PHPUnit_Framework_TestCase
+abstract class AbstractJsonRpcClientTest extends TestCase
 {
     /** @var  MockHandler */
     protected $queue;

JsonRpc/Tests/ResponseBodyValidatorTest.php

@@ -2,10 +2,13 @@
 
 namespace ScayTrase\Api\JsonRpc\Tests;
 
+use PHPUnit\Framework\TestCase;
+use ScayTrase\Api\JsonRpc\JsonRpcClient;
 use ScayTrase\Api\JsonRpc\JsonRpcErrorInterface;
 use ScayTrase\Api\JsonRpc\ResponseBodyValidator;
+use ScayTrase\Api\JsonRpc\SyncResponse;
 
-class ResponseBodyValidatorTest extends \PHPUnit_Framework_TestCase
+class ResponseBodyValidatorTest extends TestCase
 {
     public function invalidResponseBodyProvider()
     {
@@ -85,7 +88,6 @@ public function testInvalidBody(\stdClass $body)
      */
     public function testValidBody(\stdClass $body)
     {
-        $parser = new ResponseBodyValidator();
-        $parser->validate($body);
+        self::assertEquals(JsonRpcClient::VERSION, (new SyncResponse($body))->getVersion());
     }
 }

README.md

@@ -18,3 +18,85 @@ Extension of [`scaytrase/rpc-common`](https://github.com/scaytrase/rpc-common)
  * Automatic batch with multiple requests or `LazyClientDecorator`
 
 [JSON-RPC 2.0 Specification](http://www.jsonrpc.org/specification)
+
+## Usage
+
+1. Configure a [Guzzle client](http://docs.guzzlephp.org/en/latest/).
+2. Configure a Guzzle URI instance
+3. Instantiate the client:
+
+```php
+use ScayTrase\Api\JsonRpc\JsonRpcClient;
+
+$client = new JsonRpcClient($guzzleClient, new Uri('http://endpoint/url/'));
+```
+
+4. Optionally pass the ID generator as third argument and the PSR-3 logger as the fourth argument
+
+Simple UUID generator and PSR-3 `NullLogger` are used by default. ID is generated for `RpcRequestInterface` instances.
+If request is instance of `JsonRpcRequestInterface` and does not contain an ID assigned, the request is traited as 
+notification request and will not receive the response from server.
+
+5. Create a `RpcRequestInterface` instance
+
+With `JsonRpcRequest` class:
+
+```php
+$request = new \ScayTrase\Api\JsonRpc\JsonRpcRequest('my/method', ['param1' => 'val1'], 'request_id');
+$notification = new \ScayTrase\Api\JsonRpc\JsonRpcRequest('my/method', ['param1' => 'val1']);
+```
+
+With `JsonRpcNotification` class:
+```php
+$notification = new \ScayTrase\Api\JsonRpc\JsonRpcNotification('my/method', ['param1' => 'val1']);
+```
+
+With custom `RpcRequestInterface` implementation:
+
+```php
+final class MyRpcRequest implements \ScayTrase\Api\Rpc\RpcRequestInterface 
+{
+    public function getMethod() 
+    {
+        return 'my/method';
+    }
+    
+    public function getParameters() 
+    {
+        return ['param1' => 'val1'];      
+    }
+}
+
+$request = new MyRpcRequest;
+```
+
+6. Call the client
+
+```php
+/** @var \ScayTrase\Api\Rpc\RpcClientInterface $client */
+/** @var \ScayTrase\Api\Rpc\RpcRequestInterface $request */
+ 
+$collection = $client->invoke($request);
+$collection = $client->invoke([$request]);
+```
+
+The collection object contains the mapping between the requests and the responses
+
+```php
+/** @var \ScayTrase\Api\Rpc\RpcRequestInterface $request */
+/** @var \ScayTrase\Api\Rpc\ResponseCollectionInterface $collection */
+
+$response = $collection->getResponse($request);
+```
+
+## Decorating
+
+Refer [`scaytrase/rpc-common`](https://github.com/scaytrase/rpc-common) base library for some
+useful decorators, i.e `CacheableRpcClient`, `LazyRpcClient`, `LoggableRpcClient`.
+
+Also some profiling wrappers for Symfony usage were implemented:
+
+ * [Profiled client](https://github.com/bankiru/doctrine-api-bundle/blob/master/src/Bankiru/Api/Client/Profiling/ProfiledClient.php)
+ with DataCollector and Profiler integration
+ * [Traceable client](https://github.com/bankiru/doctrine-api-bundle/blob/master/src/Bankiru/Api/Client/Profiling/TraceableClient.php)
+ with Stopwatch integration

composer.json

@@ -14,11 +14,10 @@
     "scaytrase/rpc-common": "~1.0",
     "psr/log": "~1.0",
     "guzzlehttp/guzzle": "~6.0",
-    "paragonie/random_compat": "~1.1@stable"
+    "paragonie/random_compat": "^1|^2"
   },
   "require-dev": {
-    "phpunit/phpunit": "~4.5|~5.1",
-    "phpunit/php-code-coverage": "~2.1|~3.0",
+    "phpunit/phpunit": "^4.8.35|^5.4|^6.0",
     "psr/cache": "~1.0"
   },
   "autoload": {