• Major Sections
  • Home
  • Toolkit
  • Framework
  • Application
  • Installation and Repos
• Personal tools
  • Log in
• • Main page
  • Recent changes
  • Random page
  • Help
• Toolbox
  • What links here
  • Related changes
  • Special pages

Framework:sb JSON RPC2

From Surebert wiki

Overview

Surebert's JSON_RPC2 client and server were created to allow you to call remote PHP procedures directly from javascript on the clientside. This is based on the spec proposal at http://groups.google.com/group/json-rpc/web/json-rpc-1-2-proposal

Creating a Server

Creating a JSON_RPC2_Server is easy, see Framework:sb_Controller_JSON_RPC2 for more info.

sb_JSON_RPC2_Client

Used to send a JSON RPC2 Request instance to a JSON RPC2 server.

Information about using the surebert toolkit to make a JSON RPC2 call with javascript view the following: Toolkit:json:rpc2 That is how the rp people search is done.

Calling a remote method from a sb_JSON_RPC_Server with PHP

To send a request to an sb_JSON_RPC2_Server with PHP, first create a sb_JSON_RPC2_Client instance

//create a new client($host); - timeout and port are optional
$client = new sb_JSON_RPC2_Client('http://example.com/json/server');
 
//call the remote method as though it is a method of your client.
$response = $client->add(1,2);
print_raw($response);

Using $client->dispatch

You can also dispatch a request using the client's dispatch method which accepts a sb_JSON_RPC2_Request instance as its only argument. Here we are calling the remote procedure add with the params 1 and 2. Using ->dispatch returns a full sb_JSON_RPC2_Response instance with the appropriate result or error property. When more extreme performance is required, this may be a better is a better option.

$response = $client->dispatch(new sb_JSON_RPC2_Request('add', Array(1, 2)));
print_raw($response);

Sending cookies to the server

You can pass cookies to the JSON server using add_cookie

$client->add_cookie(Array('one' => 'two'));

Logging Requests/Responses

set a logger if you want to log (optional)

$client->set_logger(new sb_Logger_FileSystem());

Debugging

While you can debug to a log, you can also debug directly to output buffer so that any data returned is shown.

$client->sdebug = true;

Use Encryption

sb_JSON_RPC2_Client and Server can encrypt communication using mcrypt. In order for it to work, both client and server must use the same key.

//use encryption for transfer, pass the same key the server is using
$client->use_encryption($key);

PHP serializing response body

As of verison 1.2 sb_JSON_RPC2_Client and Server can serialize the response body as PHP before json encoding in order to preserve hashes as arrays. Otherwise they are converted to objects during json encode, which might not be ideal. The server will automagically server this way if the client requests it.

//force server to serialize response as PHP
$client->php_serialize_response = true;

Finding out what methods a sb_JSON_RPC2_Server provides

To find out what methods a server provides, call the remote procedure "get_methods". It is available by default on any sb_JSON_RPC2_Server instance. It returns an object with the methods available and any notes from your phpDocumentor code. For this reason it is critical to serve well-documented functions and methods.

Some servers may have this function turned off for security reasons.

//create a new client
$client = new sb_JSON_RPC2_Client('http://example.com/json/server');
 
//dispatch the request to a url, if you want to debug change false to true
$response = $client->get_methods();
 
print_r($response);

The above remote procedure call would return the following:

stdClass Object
(
    [get_methods] => 
	/**
	 * Get the methods available for this sb_JSON_RPC2_Server instance
	 * @return array
	 */
    [drop_punctuation] =>
	/**
 	* An example function to serve which drop non letters or numbers from a string
 	* @param $str The string to strip
 	* @return string The string minus any non letters or numbers or _
 	*/
    [add] => /**
	 * Adds two numbers together x+y
	 * @param $x integer
	 * @param $y integer
	 * @return integer
	 */
    [subtract] => /**
	 * Subtract two numbers x-y
	 * @param $x integer
	 * @param $y integer
	 * @return integer
	 */
    [multiple] => /**
	 * Mutliplies two numbers x*y
	 * @param $x integer
	 * @param $y integer
	 * @return integer
	 */
    [divide] => /**
	 * Divides two numbers x/y or throws JSON_RPC2_Error if divided by 0
	 * @param $x integer
	 * @param $y integer
	 * @return float
	 */
    [dance] => /**
	 * @param mixed  $v unlimited number of variables to display with var_dump()
	 * @return string
	 */
)

Once you know the methods you can request the phpdoc for a single method with

//create a new client
$client = new sb_JSON_RPC2_Client('http://example.com/json/server');
 
//dispatch the request to a url, if you want to debug change false to true
$response = $client->get_phpdoc('some_method');
 
print_r($response);

sb_JSON_RPC2_Request

Used to model a JSON RPC2 request.

Properties

• method - A String containing the name of the procedure to be invoked.
• params - An Array or Object, that holds the actual parameter values for the invocation of the procedure. Can be omitted if empty.
• id - A request identifier, will be returned with the respose

sb_JSON_RPC2_Response

Used to model a JSON RPC2 response

Properties

• result - Required on success, omitted on failure. The Value that was returned by the procedure. Its contents is entirely defined by the procedure. This member MUST be entirely omitted if there was an error invoking the procedure.
• error - an sb_JSON_RPC2_Error Required on error, omitted on success. An Object containing error information about the fault that occurred before, during or after the call. This member MUST be entirely omitted if there was no such fault.
• id - The same id as in the Request it is responding to. If there was an error before detecting the id in the Request, it MUST be Null.

sb_JSON_RPC2_Error

Used to model a JSON RPC2 error

Properties

• mesage - A short description of the error. The message SHOULD be limited to a concise single sentence.
• data - Additional information, may be omitted. Its contents is entirely defined by the application (e.g. detailed error information, nested errors etc.).
• code - A Number that indicates the actual error that occurred.

The error-codes -32768 .. -32000 (inclusive) are reserved for pre-defined errors.