363 lines
6.6 KiB
Markdown
363 lines
6.6 KiB
Markdown
JsonRPC PHP Client and Server
|
|
=============================
|
|
|
|
A simple Json-RPC client/server that just works.
|
|
|
|
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
|
|
- License: MIT
|
|
|
|
Requirements
|
|
------------
|
|
|
|
- The only dependency is the cURL extension
|
|
- PHP >= 5.3
|
|
|
|
Author
|
|
------
|
|
|
|
[Frédéric Guillot](http://fredericguillot.com)
|
|
|
|
Installation with Composer
|
|
--------------------------
|
|
|
|
```bash
|
|
composer require fguillot/json-rpc dev-master
|
|
```
|
|
|
|
Examples
|
|
--------
|
|
|
|
### Server
|
|
|
|
Callback binding:
|
|
|
|
```php
|
|
<?php
|
|
|
|
use JsonRPC\Server;
|
|
|
|
$server = new Server;
|
|
|
|
// Procedures registration
|
|
|
|
$server->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
|
|
<?php
|
|
|
|
use JsonRPC\Server;
|
|
|
|
class Api
|
|
{
|
|
public function doSomething($arg1, $arg2 = 3)
|
|
{
|
|
return $arg1 + $arg2;
|
|
}
|
|
}
|
|
|
|
$server = new Server;
|
|
|
|
// Bind the method Api::doSomething() to the procedure myProcedure
|
|
$server->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
|
|
<?php
|
|
|
|
use JsonRPC\Server;
|
|
use JsonRPC\AuthenticationFailure;
|
|
|
|
class Api
|
|
{
|
|
public function beforeProcedure($username, $password, $class, $method)
|
|
{
|
|
if ($login_condition_failed) {
|
|
throw new AuthenticationFailure('Wrong credentials!');
|
|
}
|
|
}
|
|
|
|
public function addition($a, $b)
|
|
{
|
|
return $a + $b;
|
|
}
|
|
}
|
|
|
|
$server = new Server;
|
|
$server->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
|
|
<?php
|
|
|
|
use JsonRPC\Client;
|
|
|
|
$client = new Client('http://localhost/server.php');
|
|
$result = $client->execute('addition', [3, 5]);
|
|
|
|
var_dump($result);
|
|
```
|
|
|
|
Example with named arguments:
|
|
|
|
```php
|
|
<?php
|
|
|
|
use JsonRPC\Client;
|
|
|
|
$client = new Client('http://localhost/server.php');
|
|
$result = $client->execute('random', ['end' => 10, 'start' => 1]);
|
|
|
|
var_dump($result);
|
|
```
|
|
|
|
Arguments are called in the right order.
|
|
|
|
Examples with shortcut methods:
|
|
|
|
```php
|
|
<?php
|
|
|
|
use JsonRPC\Client;
|
|
|
|
$client = new Client('http://localhost/server.php');
|
|
$result = $client->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
|
|
<?php
|
|
|
|
use JsonRPC\Client;
|
|
|
|
$client = new Client('http://localhost/server.php');
|
|
|
|
$results = $client->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
|
|
- `RuntimeException`: Protocol error, authentication failure or connection failure, the message describe the exact error
|
|
|
|
### Enable client debugging
|
|
|
|
You can enable the debug to see the JSON request and response:
|
|
|
|
```php
|
|
<?php
|
|
|
|
use JsonRPC\Client;
|
|
|
|
$client = new Client('http://localhost/server.php');
|
|
$client->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
|
|
<?php
|
|
|
|
use JsonRPC\Server;
|
|
|
|
$server = new Server;
|
|
|
|
// IP client restrictions
|
|
$server->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
|
|
<?php
|
|
|
|
use JsonRPC\Server;
|
|
|
|
$server = new Server;
|
|
|
|
// List of users to allow
|
|
$server->authentication(['user1' => 'password1', 'user2' => 'password2']);
|
|
|
|
// Procedures registration
|
|
|
|
[...]
|
|
|
|
// Return the response to the client
|
|
echo $server->execute();
|
|
```
|
|
|
|
On the client, set credentials like that:
|
|
|
|
```php
|
|
<?php
|
|
|
|
use JsonRPC\Client;
|
|
|
|
$client = new Client('http://localhost/server.php');
|
|
$client->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
|
|
<?php
|
|
|
|
use JsonRPC\Server;
|
|
class MyException extends RuntimeException {};
|
|
|
|
$server = new Server;
|
|
|
|
// Exceptions that should be relayed to the client, if they occur
|
|
$server->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();
|
|
```
|