Vendoring deprecated composer libs
This commit is contained in:
Frédéric Guillot
412
libs/jsonrpc/README.markdown
Normal file
412
libs/jsonrpc/README.markdown
Normal file
@@ -0,0 +1,412 @@
|
||||
JsonRPC PHP Client and Server
|
||||
=============================
|
||||
|
||||
A simple Json-RPC client/server that just works.
|
||||
|
||||
Features
|
||||
--------
|
||||
|
||||
- JSON-RPC 2.0 only
|
||||
- The server support batch requests and notifications
|
||||
- Authentication and IP based client restrictions
|
||||
- Custom Middleware
|
||||
- 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
|
||||
<?php
|
||||
|
||||
use JsonRPC\Server;
|
||||
|
||||
$server = new Server();
|
||||
$server->getProcedureHandler()
|
||||
->withCallback('addition', function ($a, $b) {
|
||||
return $a + $b;
|
||||
})
|
||||
->withCallback('random', function ($start, $end) {
|
||||
return mt_rand($start, $end);
|
||||
})
|
||||
;
|
||||
|
||||
echo $server->execute();
|
||||
```
|
||||
|
||||
Callback binding from array:
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
use JsonRPC\Server;
|
||||
|
||||
$callbacks = array(
|
||||
'getA' => function() { return 'A'; },
|
||||
'getB' => function() { return 'B'; },
|
||||
'getC' => function() { return 'C'; }
|
||||
);
|
||||
|
||||
$server = new Server();
|
||||
$server->getProcedureHandler()->withCallbackArray($callbacks);
|
||||
|
||||
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();
|
||||
$procedureHandler = $server->getProcedureHandler();
|
||||
|
||||
// Bind the method Api::doSomething() to the procedure myProcedure
|
||||
$procedureHandler->withClassAndMethod('myProcedure', 'Api', 'doSomething');
|
||||
|
||||
// Use a class instance instead of the class name
|
||||
$procedureHandler->withClassAndMethod('mySecondProcedure', new Api, 'doSomething');
|
||||
|
||||
// The procedure and the method are the same
|
||||
$procedureHandler->withClassAndMethod('doSomething', 'Api');
|
||||
|
||||
// Attach the class, the client will be able to call directly Api::doSomething()
|
||||
$procedureHandler->withObject(new Api());
|
||||
|
||||
echo $server->execute();
|
||||
```
|
||||
|
||||
Class/Method binding from array:
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
use JsonRPC\Server;
|
||||
|
||||
class MathApi
|
||||
{
|
||||
public function addition($arg1, $arg2)
|
||||
{
|
||||
return $arg1 + $arg2;
|
||||
}
|
||||
|
||||
public function subtraction($arg1, $arg2)
|
||||
{
|
||||
return $arg1 - $arg2;
|
||||
}
|
||||
|
||||
public function multiplication($arg1, $arg2)
|
||||
{
|
||||
return $arg1 * $arg2;
|
||||
}
|
||||
|
||||
public function division($arg1, $arg2)
|
||||
{
|
||||
return $arg1 / $arg2;
|
||||
}
|
||||
}
|
||||
|
||||
$callbacks = array(
|
||||
'addition' => array( 'MathApi', addition ),
|
||||
'subtraction' => array( 'MathApi', subtraction ),
|
||||
'multiplication' => array( 'MathApi', multiplication ),
|
||||
'division' => array( 'MathApi', division )
|
||||
);
|
||||
|
||||
$server = new Server();
|
||||
$server->getProcedureHandler()->withClassAndMethodArray($callbacks);
|
||||
|
||||
echo $server->execute();
|
||||
```
|
||||
|
||||
Server Middleware:
|
||||
|
||||
Middleware might be used to authenticate and authorize the client.
|
||||
They are executed before each procedure.
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
use JsonRPC\Server;
|
||||
use JsonRPC\MiddlewareInterface;
|
||||
use JsonRPC\Exception\AuthenticationFailureException;
|
||||
|
||||
class Api
|
||||
{
|
||||
public function doSomething($arg1, $arg2 = 3)
|
||||
{
|
||||
return $arg1 + $arg2;
|
||||
}
|
||||
}
|
||||
|
||||
class MyMiddleware implements MiddlewareInterface
|
||||
{
|
||||
public function execute($username, $password, $procedureName)
|
||||
{
|
||||
if ($username !== 'foobar') {
|
||||
throw new AuthenticationFailureException('Wrong credentials!');
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
$server = new Server();
|
||||
$server->getMiddlewareHandler()->withMiddleware(new MyMiddleware());
|
||||
$server->getProcedureHandler()->withObject(new Api());
|
||||
echo $server->execute();
|
||||
```
|
||||
|
||||
You can raise a `AuthenticationFailureException` when the API credentials are wrong or a `AccessDeniedException` when the user is not allowed to access to the procedure.
|
||||
|
||||
### Client
|
||||
|
||||
Example with positional parameters:
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
use JsonRPC\Client;
|
||||
|
||||
$client = new Client('http://localhost/server.php');
|
||||
$result = $client->execute('addition', [3, 5]);
|
||||
```
|
||||
|
||||
Example with named arguments:
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
use JsonRPC\Client;
|
||||
|
||||
$client = new Client('http://localhost/server.php');
|
||||
$result = $client->execute('random', ['end' => 10, 'start' => 1]);
|
||||
```
|
||||
|
||||
Arguments are called in the right order.
|
||||
|
||||
Examples with the magic method `__call()`:
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
use JsonRPC\Client;
|
||||
|
||||
$client = new Client('http://localhost/server.php');
|
||||
$result = $client->random(50, 100);
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
Client exceptions are normally thrown when an error is returned by the server. You can change this behaviour by
|
||||
using the `$returnException` argument which causes exceptions to be returned. This can be extremely useful when
|
||||
executing the batch request.
|
||||
|
||||
- `BadFunctionCallException`: Procedure not found on the server
|
||||
- `InvalidArgumentException`: Wrong procedure arguments
|
||||
- `JsonRPC\Exception\AccessDeniedException`: Access denied
|
||||
- `JsonRPC\Exception\ConnectionFailureException`: Connection failure
|
||||
- `JsonRPC\Exception\ServerErrorException`: Internal server error
|
||||
|
||||
### Enable client debugging
|
||||
|
||||
You can enable the debug mode to see the JSON request and response:
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
use JsonRPC\Client;
|
||||
|
||||
$client = new Client('http://localhost/server.php');
|
||||
$client->getHttpClient()->withDebug();
|
||||
```
|
||||
|
||||
The debug output is sent to the PHP 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 addresses:
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
use JsonRPC\Server;
|
||||
|
||||
$server = new Server;
|
||||
|
||||
// IP client restrictions
|
||||
$server->allowHosts(['192.168.0.1', '127.0.0.1']);
|
||||
|
||||
[...]
|
||||
|
||||
// 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']);
|
||||
|
||||
[...]
|
||||
|
||||
// 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->getHttpClient()
|
||||
->withUsername('Foo')
|
||||
->withPassword('Bar');
|
||||
```
|
||||
|
||||
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')`.
|
||||
|
||||
### Local Exceptions
|
||||
|
||||
By default, the server will relay all exceptions to the client.
|
||||
If you would like to relay only some of them, use the method `Server::withLocalException($exception)`:
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
use JsonRPC\Server;
|
||||
class MyException1 extends Exception {};
|
||||
class MyException2 extends Exception {};
|
||||
|
||||
$server = new Server();
|
||||
|
||||
// Exceptions that should NOT be relayed to the client, if they occurs
|
||||
$server
|
||||
->withLocalException('MyException1')
|
||||
->withLocalException('MyException2')
|
||||
;
|
||||
|
||||
[...]
|
||||
|
||||
echo $server->execute();
|
||||
```
|
||||
|
||||
### Callback before client request
|
||||
|
||||
You can use a callback to change the HTTP headers or the URL before to make the request to the server.
|
||||
|
||||
Example:
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
$client = new Client();
|
||||
$client->getHttpClient()->withBeforeRequestCallback(function(HttpClient $client, $payload) {
|
||||
$client->withHeaders(array('Content-Length: '.strlen($payload)));
|
||||
});
|
||||
|
||||
$client->myProcedure(123);
|
||||
```
|
||||
Reference in New Issue
Block a user