Client Side with cache
Introduction about the XML_RPC2 "cached client side" usage
Thanks to PHP5 and PEAR/Cache_Lite, it's really easy to do XMLRPC "cached client" requests with XML_RPC2. The usage is really straightforward.
First, you include 'XML/RPC2/CachedClient.php' file (only this one).
<?php
require_once 'XML/RPC2/CachedClient.php';
?>
Second, you make an assocative arrays of options to tune XML_RPC2 (prefix, proxy, manual backend choice...).
<?php
$options = array(
'prefix' => 'package.',
'cacheOptions' => array(
'cacheDir' => '/tmp/',
'lifetime' => 3600
)
);
?>
Third, you make a XML_RPC2_CachedClient object with the server URL and the with the options array.
<?php
$client = XML_RPC2_CachedClient::create('http://pear.php.net/xmlrpc.php', $options);
?>
Then, you send your request by calling the server method as it was a local method of the $client object.
<?php
$result = $client->info('XML_RPC2');
?>
This single line will encode a XMLRPC client request for the package.info() (prefix + method name) method with a single argument (the string 'XML_RPC2'), will send the request over HTTP to the server and will decode the response into PHP native types. With a single line ! Moreover, the result will be cached into a file for the given lifetime. So the next call will not send any HTTP request and it will be really fast.
Of course, to catch server errors, you have to add a few lines around you client call like for example :
<?php
try {
$result = $client->info('XML_RPC2');
print_r($result);
} catch (XML_RPC2_FaultException $e) {
// The XMLRPC server returns a XMLRPC error
die('Exception #' . $e->getFaultCode() . ' : ' . $e->getFaultString());
} catch (Exception $e) {
// Other errors (HTTP or networking problems...)
die('Exception : ' . $e->getMessage());
}
?>
The options array
This array is completely optional but really usefull. The following keys are available :
| Option | Data Type | Default Value | Description |
|---|---|---|---|
| [...] | [...] | [...] | See "non cached client side" for more options |
| cacheOptions | array | array() | See next table for a complete description |
"CacheOptions" entry is an associative array. Available keys are :
| Option | Data Type | Default Value | Description |
|---|---|---|---|
| [...] | [...] | [...] | See "Cache_Lite constructor" for more options |
| defaultCacheGroup | string | '' | Name of the default cache group |
| cachedMethods | array | array() | Array of method names to be cached (if cacheByDefault is false) |
| notCachedMethods | array | array() | Array of method names not to be cached (if cacheByDefault is true) |
| cacheByDefault | boolean | TRUE | if true, the cache is "on" by default ; else, only methods listed in cachedMethods will be cached |
Making the XML_RPC2_CachedClient object
It's really easy to make the XML_RPC2_CachedClient object. Use the following syntax :
<?php
// $XMLRPCServerURL is a string : 'http://pear.php.net/xmlrpc.php' (for example)
// $options is an optional array : see previous section for more informations
$client = XML_RPC2_CachedClient::create($XMLRPCServerURL, $options);
?>
Don't try to call the XML_RPC2_CachedClient constructor directly, use the call() static method.
Call the XMLRPC exported method
See "non cached client side" documentation, there is no difference.
The caching process is completly embedded and automatic. If a cache is available, result will be get from cache and no HTTP request will be sent. If there is no cache available for this particular call (method name and arguments), the classical XMLRPC communication will be used (and the result will be stored into a cache file for the next use).