PEAR Manual
PrevNext

Client Side with cache

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). 
require_once 'XML/RPC2/CachedClient.php';

Second, you make an assocative arrays of options to tune XML_RPC2 (prefix, proxy, manual backend choice...). 
$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. 
$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. 
$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 : 
try {
    $result = $client->info('XML_RPC2'); 
    print_r($result);
} catch (XML_RPC2_FaultException $e) {
    // The XMLRPC server returns a XMLRPC error
    die('Exception #' . $result->getFaultCode() . ' : ' . $e->getFaultString());
} catch (Exception $e) {  
    // Other errors (HTTP or networking problems...)
    die('Exception : ' . $e->getFaultString());
}

The options array

This array is completely optional but really usefull. The following keys are available :

Table 60-1. Options available keys

OptionData TypeDefault ValueDescription
[...][...][...]See "non cached client side" for more options
cacheOptionsarrayarray()See next table for a complete description
"CacheOptions" entry is an associative array. Available keys are :

Table 60-2. CacheOptions available keys

OptionData TypeDefault ValueDescription
[...][...][...]See "Cache_Lite constructor" for more options
defaultCacheGroupstring''Name of the default cache group
cachedMethodsarrayarray()Array of method names to be cached (if cacheByDefault is false)
notCachedMethodsarrayarray()Array of method names not to be cached (if cacheByDefault is true)
cacheByDefaultbooleanTRUE 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 : 
// $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).

PrevHomeNext
Server SideUpServer Side with cache