The trated themes require the knowledge of the specification of the JSON-RPC 1.0 protocol.
The jsonRPCServer class contains only one static method jsonRPCServer::handle(), responding to the JSON-RPC requests.
jsonRPCServer::handle() — Forward a JSON-RPC request to a given object and respond to the client
boolean jsonRPCServer::handle (object $object)
Collect a valid JSON-RPC request and search the corresponding method in $object, using the request's parameters as method parameters.
The response is given as JSON-RPC response.
The request is valid if it is a POST request and if it has a Content-Type: application/json. Either if the request is invalid or if it is a notification (see http://json-rpc.org/wiki/specification, 1.3 Notification), no response will be given to the JSON-RPC client.
object — The object whom the JSON-RCP request will be forwarded to.
Returns TRUE if the JSON-RPC request is well formed (i.e. a POST request with Content-Type: application/json). Otherwise, returns FALSE to the main program and don't give a response to the JSON-RPC client.
<?php
require_once 'jsonRPCServer.php';
require 'example.php';
$myExample = new example();
jsonRPCServer::handle($myExample)
or print 'no request';
?>
If a request is valid (i.e. is a POST request with Content-Type: application/json) but contains some errors (e.g. the requested method doesn't exist in $object or the parameters structure is not valid) the jsonRPCServer::handle method returns TRUE to the calling program, but returns an error message to the JSON-RPC client.
This happens because informing the server side about a wrong client reqeust donesn't make sense, while the client must be informed about the bad quality of its message.
The JSON-RPC protocol contains a simple and full error management system rightly to this pourpose.
The jsonRPCclient class contains three public methods: the constructor jsonRPCClient->__construct(), the jsonRPCClient->__call() method, forwarding the requests to the JSON-RPC server, and the jsonRPCClient->setRPCNotification(), to establish if the requests are normal requests or notifications.
jsonRPCClient->__construct() — Create a new jsonRPCClient object linking it to a JSON-RPC server
class jsonRPCClient {
__construct (string $url[, boolean $debug])
}
Create a new jsonRPCClient object linking it to a JSON-RPC server. The created object contains all JSON-RPC service's methods, each with the same parameters, and the methods return the same service structured values.
If required, setting to TRUE the $debug value, debugging informations are sent to the stdout.
url — The JSON-RPS service's URL.
debug — I TRUE, output on the stdout the dialog between server and client. The default value is FALSE.
Return a jsonRPCClient object.
<?php
require_once 'jsonRPCClient.php';
$myExample = new jsonRPCClient('http://somehostname/path/jsonRPCserver');
?>
jsonRPCClient->__call() — Load any called method in the corresponding method of the JSON-RPC server, forwarding the given parameters
class jsonRPCClient {
mixed __call (string $method, array $params)
}
Wathever be the called method for the jsonRPCClient object, __call() converts it in the JSON-RPC method with the same name. The parameters also are forwarded in a fully transaparent way.
__call() is a magic method, it must NOT be called with its own name. It collect every method called (except the explicitely defined ones), converting them in the JSON-RPC form.
method — The name of the required method.
params — The parameters set packaged as an array.
Return the structured value given by the called method. If the method is called as a notification, return TRUE.
<?php
require_once 'jsonRPCClient.php';
$myExample = new jsonRPCClient('http://somehostname/path/jsonRPCserver');
try {
echo 'Your name is <i>'.$myExample->giveMeSomeData('name').'</i><br />'."\n";
$myExample->changeYourState('I am using this function from the network');
echo 'Your status request has been accepted<br />'."\n";
} catch (Exception $e) {
echo nl2br($e->getMessage()).'<br />'."\n";
}
?>
Keep in mind the example: the __call() method isn't called explicitely. Instead, methods that aren't between the explicitely decalred methods of the class are called. These are the JSON-RPC service's methods.
__call() collect every method request not coresponding to any explicitely declared method of the class and manage it as JSON-RPC requests. The parameters too are given as the JSON-RPC method requires, where __call() will package them in an array.
In this way, the __call() method charges on itself the requests and act as a proxy to the JSON-RPC server.
jsonRPCClient->setRPCnotification() — Set the internal state of the object, to determine if the requests are sent as normal requests or notifications
class jsonRPCClient {
void setRPCnotification() (boolean $notification)
}
If a notification form is needed (see http://json-rpc.org/wiki/specification, 1.3 Notification), a TRUE parameter must be sent to setRPCnotification(), before doing the request. From that moment every request will have the notification form.
Send back a FALSE value to setRPCnotification() to restore the normal requests (with response).
notification — A boolean value that should be TRUE if the requests must be notifications, FALSE if th requests must have a response.
<?php
require_once 'jsonRPCClient.php';
$myExample = new jsonRPCClient('http://somehostname/path/jsonRPCserver');
try {
echo 'Your name is <i>'.$myExample->giveMeSomeData('name').'</i><br />'."\n";
$myExample->setRPCnotification(true);
$myExample->changeYourState('I am using this function from the network');
echo 'Your status request has been accepted<br />'."\n";
$myExample->setRPCnotification(false);
echo 'Your personl attribute is <i>'.$myExample->giveMeSomeData('attr').'</i><br />'."\n";
} catch (Exception $e) {
echo nl2br($e->getMessage()).'<br />'."\n";
}
?>
In the method's requests there isn't a parameter indicating if the requests must be of the notification form, i.e., with no response.
As default, every request is a request expecting a response.
This happens to grant the best fit between the JSON-RPc method form and the object form. Moreover, notifications don't fit to the way to write code in PHP, where every operation has a returned value.
For these reasons, setRPCnotification() has been prepared as a separated switch, to be intended as a state modifier.
