Skip to content

Client usage

Jump to bottom
johnstevenson edited this page Oct 27, 2012 · 6 revisions

Contents

The Basics

The library provides a very easy way to make Json-Rpc request calls, including notification and batch requests. For all cases you first need to instantiate a JsonRpc\Client, which you do by giving it the url you want to send your requests to:

<?php
$client = new JsonRpc\Client($url);

Requests

You send a request by using the $client->call function. This takes the name of the method you want to invoke on the server and its parameters, if it requires any. The only tricky bit here is remembering to put the parameters into an array, similar to PHP's call_user_func_array function.

<?php
$success = $client->call('method', array($param1, $param2));

The function returns true or false. If true then the result of the method will be in the $client->result property. The type of the result depends on what has been returned by the server, so it could be a scalar, an indexed array, an object stdClass, or null.

If false then an error has occurred, either in sending or processing the request. This is reported in the $client->error property, which is a string. Putting it all together:

<?php
$client = new JsonRpc\Client($url);

if ($client->call('method', array($param1, $param2)))
{
  return $client->result;
}
else
{
  error_log($client->error);
}

Tip: If you just want a client to send simple requests, then there is no need to read any further. However the next sections explain notification and batch requests.

Notification Requests

A notification is a call to the server which does not require a response. You send one by using the $client->notify function, which takes the same arguments as the $client->call function described above:

<?php
$success = $client->notify('method', array($param));

The function returns either true, meaning that the request was sent and received, or false, indicating that there was an error sending the request which will be reported in the $client->error property.

Note that there is no way of knowing if the server encountered an error while processing your request, for example if you supplied the wrong parameters. Such is the nature of notifications.

Batch Requests

A batch request is one which sends several requests at the same time, including notifications:

  • call the $client->batchOpen function to start a batch operation
  • populate the batch by making $client->call and $client->notify calls
  • send the batch with the $client->batchSend function.
<?php
$client->batchOpen();

$client->call('divide', array(42, 6));
$client->call('method2', array($param1, $param2));
$client->notify('update', array($param);
  ...
$success = $client->batchSend();

The function returns either true, meaning that the batch has been processed, or false, indicating that there was an error sending the batch request which will be reported in the $client->error property.

You have to do a bit more work to process the response from a batch operation, which will be in the $client->batch property. This is an indexed array of all the responses from the server, each being a stdClass object representing a result or an error. Using the example above and assuming that method2 was not found on the server, this is what $client->batch looks like:

Array
(
    [0] => stdClass Object
        (
          [jsonrpc] => 2.0
          [result] => 7
          [id] => 1
        )

    [1] => stdClass Object
        (
          [jsonrpc] => 2.0
          [error] => stdClass Object
            (
              [code] => -32601
              [message] => Method not found
            )
          [id] => 2
        )
)

Note that responses have been assigned an id property, which is allocated with each $client->call ascending from 1. The responses returned in the $client->batch array are similarly ordered (even though they may have been received out of sequence). Notifications do not have an id or a response.

It is worth reading the official specification if you want to make batch requests. Also the example found at example/client.php is very useful to experiment with.

Errors and Exceptions

Any errors that are caused by your accidental bad input result in an \Exception being thrown. This will happen in the following circumstances:

  • if you pass invalid values to either the client->call or client->notify functions
  • if you call $client->batchSend with a single request

Any subsequent errors that occur whilst processing the request are returned in the client->error property.

Advanced

The built-in transport mechanism uses file_get_contents to communicate with the server. If this is too restrictive you can create your own transport mechanism (using curl, for example). See the Advanced functionality topic for more details.

Clone this wiki locally