JsonRPC PHP Client and Server ============================= A simple Json-RPC client/server that just works. [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/fguillot/JsonRPC/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/fguillot/JsonRPC/?branch=master) [![Build Status](https://travis-ci.org/fguillot/JsonRPC.svg?branch=master)](https://travis-ci.org/fguillot/JsonRPC) Features -------- - JSON-RPC 2.0 protocol only - The server support batch requests and notifications - Authentication and IP based client restrictions - Minimalist: there is only 2 files - Fully unit tested - Requirements: PHP >= 5.3.4 - License: MIT Author ------ Frédéric Guillot Installation with Composer -------------------------- ```bash composer require fguillot/json-rpc @stable ``` Examples -------- ### Server Callback binding: ```php register('addition', function ($a, $b) { return $a + $b; }); $server->register('random', function ($start, $end) { return mt_rand($start, $end); }); // Return the response to the client echo $server->execute(); ?> ``` Class/Method binding: ```php bind('myProcedure', 'Api', 'doSomething'); // Use a class instance instead of the class name $server->bind('mySecondProcedure', new Api, 'doSomething'); // The procedure and the method are the same $server->bind('doSomething', 'Api'); // Attach the class, client will be able to call directly Api::doSomething() $server->attach(new Api); echo $server->execute(); ?> ``` Before callback: Before each procedure execution, a custom method can be called. This method receive the following arguments: `$username, $password, $class, $method`. ```php authentication(['myuser' => 'mypassword']); // Register the before callback $server->before('beforeProcedure'); $server->attach(new Api); echo $server->execute(); ?> ``` You can use this method to implements a custom authentication system or anything else. If you would like to reject the authentication, you can throw the exception `JsonRPC\AuthenticationFailure`. ### Client Example with positional parameters: ```php execute('addition', [3, 5]); var_dump($result); ``` Example with named arguments: ```php execute('random', ['end' => 10, 'start' => 1]); var_dump($result); ``` Arguments are called in the right order. Examples with shortcut methods: ```php random(50, 100); var_dump($result); ``` The example above use positional arguments for the request and this one use named arguments: ```php $result = $client->random(['end' => 10, 'start' => 1]); ``` ### Client batch requests Call several procedures in a single HTTP request: ```php batch() ->foo(['arg1' => 'bar']) ->random(1, 100) ->add(4, 3) ->execute('add', [2, 5]) ->send(); print_r($results); ``` All results are stored at the same position of the call. ### Client exceptions - `BadFunctionCallException`: Procedure not found on the server - `InvalidArgumentException`: Wrong procedure arguments - `JsonRPC\AccessDeniedException`: Access denied - `JsonRPC\ConnectionFailureException`: Connection failure - `JsonRPC\ServerErrorException`: Internal server error - `RuntimeException`: Protocol error ### Enable client debugging You can enable the debug to see the JSON request and response: ```php debug = true; ``` The debug output is sent to the PHP's system logger. You can configure the log destination in your `php.ini`. Output example: ```json ==> Request: { "jsonrpc": "2.0", "method": "removeCategory", "id": 486782327, "params": [ 1 ] } ==> Response: { "jsonrpc": "2.0", "id": 486782327, "result": true } ``` ### IP based client restrictions The server can allow only some IP adresses: ```php allowHosts(['192.168.0.1', '127.0.0.1']); // Procedures registration [...] // Return the response to the client echo $server->execute(); ``` If the client is blocked, you got a 403 Forbidden HTTP response. ### HTTP Basic Authentication If you use HTTPS, you can allow client by using a username/password. ```php authentication(['user1' => 'password1', 'user2' => 'password2']); // Procedures registration [...] // Return the response to the client echo $server->execute(); ``` On the client, set credentials like that: ```php authentication('user1', 'password1'); ``` If the authentication failed, the client throw a RuntimeException. Using an alternative authentication header: ```php use JsonRPC\Server; $server = new Server; $server->setAuthenticationHeader('X-Authentication'); $server->authentication(['myusername' => 'mypassword']); ``` The example above will use the HTTP header `X-Authentication` instead of the standard `Authorization: Basic [BASE64_CREDENTIALS]`. The username/password values need be encoded in base64: `base64_encode('username:password')`. ### Exceptions If you want to send an error to the client you can throw an exception. You should configure which exceptions should be relayed to the client first: ```php attachException('MyException'); // Procedures registration [...] // Return the response to the client echo $server->execute(); ``` Then you can throw that exception inside your procedure: ``` throw new MyException("An error occured", 123); ``` To relay all exceptions regardless of type, leave out the exception class name: ``` $server->attachException(); ```