PEAR Manual
Prev |  | Next

# Client Side

Client Side --

## Introduction about the XML_RPC2 client side usage

Thanks to PHP5, it's really easy to do XMLRPC client requests with XML_RPC2. The usage is really straightforward.

First, you include 'XML/RPC2/Client.php' file (only this one).

    require_once 'XML/RPC2/Client.php';

Second, you make an assocative arrays of options to tune XML_RPC2 (prefix, proxy, manual backend choice...).

    $options = array(
        'prefix' => 'package.'
    );

Third, you make a XML_RPC2_Client object with the server URL and the with the options array.

    $client = XML_RPC2_Client::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 !

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

Option | Data Type | Default Value | Description
--- | --- | --- | ---
prefix | string | '' | Prefix added before XMLRPC called method name
proxy | string | '' | Proxy used for the HTTP request (default : no proxy)
debug | boolean | `FALSE` | Debug mode ?
encoding | string | '' | Encoding of the request 'utf-8', 'iso-8859-1' (for now, only these two ones are officialy supported)
uglyStructHack | boolean | `TRUE` | ugly hack to circumvent a XMLRPCEXT bug/feature , see this PHP bug for more details. The only (reasonable) counterpart of this hack is that you can't use structs with a key beginning with the string 'xml_rpc2_ugly_struct_hack_' as arguments of the called method.

TO BE CONTINUED TO BE CONTINUED TO BE CONTINUED

## Making the XML_RPC2_Client object

It's really easy to make the XML_RPC2_Client 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_Client::create($XMLRPCServerURL, $options);

Don't try to call the XML_RPC2_Client constructor directly, use the call() static method.

## Call the XMLRPC exported method

When the XML_RPC2_Client object is created, you can directly call the remote method as it was local. For example :

    // We call the remote foo() method without any arguments
    $result1 = $client->foo();

    // We call the remote bar() method with two arguments (an integer : 123, a string : 'foo')
    $result2 = $client->bar(123, 'foo');

    // We call the remote foobar() method with complex data types (2 integer, a string, a structure)
    $result3 = $client->foobar(1, 2, 'foo', array('foo' => 1, 'bar' => 2));

Be carefull, XMLRPC spec allows some remote method names with some special characters like "." or "/"... which are not available as PHP method names. To deal with them, you have to fix a prefix in a the options array. For example :

    $options = array('prefix' => 'foo.');
    $client = XML_RPC2_Client::create('http://...', $options);

    // We call the foo.bar() method because of the prefix 'foo.' fixed in $options array
    $result = $client->bar();

In most cases, XML_RPC2 transforms automatically PHP native types into XMLRPC types (as described in the SPEC) for the request. In most cases too, XML_RPC2 transforms the XML server response into PHP native types too. Yet, there are two exceptions : 'dateTime.iso8601' and 'base64' which doesn't really exist in PHP.

To manipulate explicitely these two types, you have to use special objects. Let's see a complete example :

    <?php

    // Classic usage
    require_once 'XML/RPC2/Client.php';

    // To manipulate these types, we need to include this file too
    require_once 'XML/RPC2/Value.php';

    // To get a 'dateTime.iso8601' object, you have first to set a string with an iso8601 encoded date :
    $tmp = "20060116T19:14:03";

    // Then, you call this static method to get your 'dateTime.iso8601' object
    $time = XML_RPC2_Value::createFromNative($tmp, 'datetime');

    // For 'base64', you call the same static method with your string to get a 'base64' object
    $base64 = XML_RPC2_Value::createFromNative('foobar', 'base64');

    // Then, you can use XML_RPC2_Client as usal :
    $options = array('prefix' => 'validator1.');
    $client = XML_RPC2_Client::create('http://phpxmlrpc.sourceforge.net/server.php', $options);
    $result = $client->manyTypesTest(1, true, 'foo', 3.14159, $time, $base64);

    // The remote validator1.manyTypesTest() method returns an array with the 6 given arguments
    $result_datetime = $result[4]; // a 'dateTime.iso8601' object
    $result_base64 = $result[5];   // a 'base64' object

    // To transform these objects into PHP native types, you have to use public properties of
    // these objects as follow :
    var_dump($result_datetime->scalar);      // will return string(17) "20060116T19:14:03"
    var_dump($result_datetime->xmlrpc_type); // will return string(8) "datetime"
    var_dump($result_datetime->timestamp);   // will return int(1137435243)
    var_dump($result_base64->scalar);        // will return string(6) "foobar"
    var_dump($result_base64->xmlrpc_type);   // will return string(6) "base64"

    ?>

Prev | Home | Next
Introduction | Up | Server Side