README

JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol.

Request object

A rpc call is represented by sending a Request object to a Server.

// client
$request = new \JsonRpc\Spec\Request('subtract', [42, 23], 1);

// server
$result = call_user_func_array($request->getMethod(), $request->getParams());

Notification

A Notification is a Request object without an "id" member.

$request1 = new \JsonRpc\Spec\Request('update', [1,2,3,4,5]);
$request2 = new \JsonRpc\Spec\Request('foobar');

Response object

When a rpc call is made, the Server MUST reply with a Response, except for in the case of Notifications.

$response = new \JsonRpc\Spec\Response($result, null, $request->getId());

Error object

When a rpc call encounters an error, the Response Object MUST contain the Error member with a value that is a \JsonRpc\Spec\Error

$error = new \JsonRpc\Spec\Error(500, 'Internal error', $exception->getTraceAsString());
$response = new \JsonRpc\Spec\Response(null, $error, $request->getId());

The error codes from and including -32768 to -32000 are reserved for pre-defined errors.

use \JsonRpc\Spec\Exception\ParseErrorException;

try {
    // parse request
    throw new ParseErrorException();
} catch(ParseErrorException $e) {
    $error = new \JsonRpc\Spec\Error($e->getCode(), $e->getMessage(), $e->getTraceAsString());
    $response = new \JsonRpc\Spec\Response(null, $error, $request->getId());    
}

Batch

To send several Request objects at the same time, the Client MAY send an Array filled with Request objects.

foreach($batch as $response) {
    $result = $response->getResult();
}

BatchRequest

$requests = [
    new \JsonRpc\Spec\Request('update', [1,2,3,4,5]),
    new \JsonRpc\Spec\Request('foobar'),
    // ...
];
$batch = new \JsonRpc\Spec\BatchRequest($requests);

BatchResponse

$responses = [
    new \JsonRpc\Spec\Response(7, 1),
    new \JsonRpc\Spec\Response(null, $error, 2),
    // ...
];
$batch = new \JsonRpc\Spec\BatchResponse($responses);

ObjectManager

Object manager is a wrapper for dealing with requests/responses

$manager = new \JsonRpc\ObjectManager($transport);
$id = $manager->addRequest('subtract', [42, 23]);
$manager->addNotification('foobar');
$manager->commit();
if (!$manager->hasError($id)) {
    $result = $manager->getResult($id); // 19
} else {
    throw new Exception($manager->getError($id), $manager->getErrorCode($id));
}

Transport

The object manager uses a transport object to communicate with a transport layer (http, rabbitmq, etc). The transport object must implements the \JsonRpc\TransportInterface.

class CurlTransport implements \JsonRpc\TransportInterface 
{
    public function send(UnitInterface $data) 
    {
        $ch = curl_init();        
        
        $data = json_encode($data);        
        
        curl_setopt($ch, CURLOPT_URL, 'http://localhost/rpc.php');
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
        
        curl_exec($ch);  
    }
}

Testing

$ phpunit

License

The MIT License (MIT). Please see License File for more information.

igaponov / jsonrpc

Maintainers

Details