# Zend_XmlRpc_Server

## Introduction

`Zend_XmlRpc_Server` is intended as a fully-featured XML-RPC server, following the specifications outlined at www.xmlrpc.com. Additionally, it implements the `system.multicall()` method, allowing boxcarring of requests.

## Basic Usage

An example of the most basic use case:

    $server = new Zend_XmlRpc_Server();
    $server->setClass('My_Service_Class');
    echo $server->handle();

## Server Structure

`Zend_XmlRpc_Server` is composed of a variety of components, ranging from the server itself to request, response, and fault objects.

To bootstrap `Zend_XmlRpc_Server`, the developer must attach one or more classes or functions to the server, via the `setClass()` and `addFunction()` methods.

Once done, you may either pass a `Zend_XmlRpc_Request` object to `Zend_XmlRpc_Server::handle()`, or it will instantiate a `Zend_XmlRpc_Request_Http` object if none is provided -- thus grabbing the request from `php://input`.

`Zend_XmlRpc_Server::handle()` then attempts to dispatch to the appropriate handler based on the method requested. It then returns either a `Zend_XmlRpc_Response`-based object or a `Zend_XmlRpc_Server_Fault`object. These objects both have `__toString()` methods that create valid XML-RPC XML responses, allowing them to be directly echoed.

## Conventions

`Zend_XmlRpc_Server` allows the developer to attach functions and class method calls as dispatchable XML-RPC methods. Via `Zend_Server_Reflection`, it does introspection on all attached methods, using the function and method docblocks to determine the method help text and method signatures.

XML-RPC types do not necessarily map one-to-one to PHP types. However, the code will do its best to guess the appropriate type based on the values listed in @param and @return lines. Some XML-RPC types have no immediate PHP equivalent, however, and should be hinted using the XML-RPC type in the PHPDoc. These include:

- dateTime.iso8601, a string formatted as '`YYYYMMDDTHH:mm:ss`'

- base64, base64 encoded data

- struct, any associative array

An example of how to hint follows:

    /**
    * This is a sample function
    *
    * @param base64 $val1 Base64-encoded data
    * @param dateTime.iso8601 $val2 An ISO date
    * @param struct $val3 An associative array
    * @return struct
    */
    function myFunc($val1, $val2, $val3)
    {
    }

PhpDocumentor does no validation of the types specified for params or return values, so this will have no impact on your API documentation. Providing the hinting is necessary, however, when the server is validating the parameters provided to the method call.

It is perfectly valid to specify multiple types for both params and return values; the XML-RPC specification even suggests that system.methodSignature should return an array of all possible method signatures (i.e., all possible combinations of param and return values). You may do so just as you normally would with PhpDocumentor, using the '|' operator:

    /**
    * This is a sample function
    *
    * @param string|base64 $val1 String or base64-encoded data
    * @param string|dateTime.iso8601 $val2 String or an ISO date
    * @param array|struct $val3 Normal indexed array or an associative array
    * @return boolean|struct
    */
    function myFunc($val1, $val2, $val3)
    {
    }

One note, however: allowing multiple signatures can lead to confusion for developers using the services; generally speaking, an XML-RPC method should only have a single signature.

## Utilizing Namespaces

XML-RPC has a concept of namespacing; basically, it allows grouping XML-RPC methods by dot-delimited namespaces. This helps prevent naming collisions between methods served by different classes. As an example, the XML-RPC server is expected to server several methods in the 'system' namespace:

- system.listMethods

- system.methodHelp

- system.methodSignature

Internally, these map to the methods of the same name in `Zend_XmlRpc_Server`.

If you want to add namespaces to the methods you serve, simply provide a namespace to the appropriate method when attaching a function or class:

    // All public methods in My_Service_Class will be accessible as
    // myservice.METHODNAME
    $server->setClass('My_Service_Class', 'myservice');

    // Function 'somefunc' will be accessible as funcs.somefunc
    $server->addFunction('somefunc', 'funcs');

## Custom Request Objects

Most of the time, you'll simply use the default request type included with `Zend_XmlRpc_Server`, `Zend_XmlRpc_Request_Http`. However, there may be times when you need XML-RPC to be available via the CLI, a GUI, or other environment, or want to log incoming requests. To do so, you may create a custom request object that extends `Zend_XmlRpc_Request`. The most important thing to remember is to ensure that the `getMethod()` and `getParams()` methods are implemented so that the XML-RPC server can retrieve that information in order to dispatch the request.

## Custom Responses

Similar to request objects, `Zend_XmlRpc_Server` can return custom response objects; by default, a `Zend_XmlRpc_Response_Http` object is returned, which sends an appropriate Content-Type HTTP header for use with XML-RPC. Possible uses of a custom object would be to log responses, or to send responses back to `STDOUT`.

To use a custom response class, use `Zend_XmlRpc_Server::setResponseClass()` prior to calling `handle()`.

## Handling Exceptions via Faults

`Zend_XmlRpc_Server` catches Exceptions generated by a dispatched method, and generates an XML-RPC fault response when such an exception is caught. By default, however, the exception messages and codes are not used in a fault response. This is an intentional decision to protect your code; many exceptions expose more information about the code or environment than a developer would necessarily intend (a prime example includes database abstraction or access layer exceptions).

Exception classes can be whitelisted to be used as fault responses, however. To do so, simply utilize `Zend_XmlRpc_Server_Fault::attachFaultException()` to pass an exception class to whitelist:

    Zend_XmlRpc_Server_Fault::attachFaultException('My_Project_Exception');

If you utilize an exception class that your other project exceptions inherit, you can then whitelist a whole family of exceptions at a time. `Zend_XmlRpc_Server_Exception`s are always whitelisted, to allow reporting specific internal errors (undefined methods, etc.).

Any exception not specifically whitelisted will generate a fault response with a code of '404' and a message of 'Unknown error'.

## Caching Server Definitions Between Requests

Attaching many classes to an XML-RPC server instance can utilize a lot of resources; each class must introspect using the Reflection API (via `Zend_Server_Reflection`), which in turn generates a list of all possible method signatures to provide to the server class.

To reduce this performance hit somewhat, `Zend_XmlRpc_Server_Cache` can be used to cache the server definition between requests. When combined with `__autoload()`, this can greatly increase performance.

An sample usage follows:

    function __autoload($class)
    {
        Zend_Loader::loadClass($class);
    }

    $cacheFile = dirname(__FILE__) . '/xmlrpc.cache';
    $server = new Zend_XmlRpc_Server();

    if (!Zend_XmlRpc_Server_Cache::get($cacheFile, $server)) {
        require_once 'My/Services/Glue.php';
        require_once 'My/Services/Paste.php';
        require_once 'My/Services/Tape.php';

        $server->setClass('My_Services_Glue', 'glue');   // glue. namespace
        $server->setClass('My_Services_Paste', 'paste'); // paste. namespace
        $server->setClass('My_Services_Tape', 'tape');   // tape. namespace

        Zend_XmlRpc_Server_Cache::save($cacheFile, $server);
    }

    echo $server->handle();

The above example attempts to retrieve a server definition from xmlrpc.cache in the same directory as the script. If unsuccessful, it loads the service classes it needs, attaches them to the server instance, and then attempts to create a new cache file with the server definition.

## Usage Examples

Below are several usage examples, showing the full spectrum of options available to developers. Usage examples will each build on the previous example provided.

### Basic Usage

The example below attaches a function as a dispatchable XML-RPC method and handles incoming calls.

    /**
     * Return the MD5 sum of a value
     *
     * @param string $value Value to md5sum
     * @return string MD5 sum of value
     */
    function md5Value($value)
    {
        return md5($value);
    }

    $server = new Zend_XmlRpc_Server();
    $server->addFunction('md5Value');
    echo $server->handle();

### Attaching a class

The example below illustrates attaching a class' public methods as dispatchable XML-RPC methods.

    require_once 'Services/Comb.php';

    $server = new Zend_XmlRpc_Server();
    $server->setClass('Services_Comb');
    echo $server->handle();

### Attaching several classes using namespaces

The example below illustrates attaching several classes, each with their own namespace.

    require_once 'Services/Comb.php';
    require_once 'Services/Brush.php';
    require_once 'Services/Pick.php';

    $server = new Zend_XmlRpc_Server();
    $server->setClass('Services_Comb', 'comb');   // methods called as comb.*
    $server->setClass('Services_Brush', 'brush'); // methods called as brush.*
    $server->setClass('Services_Pick', 'pick');   // methods called as pick.*
    echo $server->handle();

### Specifying exceptions to use as valid fault responses

The example below allows any `Services_Exception`-derived class to report its code and message in the fault response.

    require_once 'Services/Exception.php';
    require_once 'Services/Comb.php';
    require_once 'Services/Brush.php';
    require_once 'Services/Pick.php';

    // Allow Services_Exceptions to report as fault responses
    Zend_XmlRpc_Server_Fault::attachFaultException('Services_Exception');

    $server = new Zend_XmlRpc_Server();
    $server->setClass('Services_Comb', 'comb');   // methods called as comb.*
    $server->setClass('Services_Brush', 'brush'); // methods called as brush.*
    $server->setClass('Services_Pick', 'pick');   // methods called as pick.*
    echo $server->handle();

### Utilizing a custom request object

The example below instantiates a custom request object and passes it to the server to handle.

    require_once 'Services/Request.php';
    require_once 'Services/Exception.php';
    require_once 'Services/Comb.php';
    require_once 'Services/Brush.php';
    require_once 'Services/Pick.php';

    // Allow Services_Exceptions to report as fault responses
    Zend_XmlRpc_Server_Fault::attachFaultException('Services_Exception');

    $server = new Zend_XmlRpc_Server();
    $server->setClass('Services_Comb', 'comb');   // methods called as comb.*
    $server->setClass('Services_Brush', 'brush'); // methods called as brush.*
    $server->setClass('Services_Pick', 'pick');   // methods called as pick.*

    // Create a request object
    $request = new Services_Request();

    echo $server->handle($request);

### Utilizing a custom response object

The example below illustrates specifying a custom response class for the returned response.

    require_once 'Services/Request.php';
    require_once 'Services/Response.php';
    require_once 'Services/Exception.php';
    require_once 'Services/Comb.php';
    require_once 'Services/Brush.php';
    require_once 'Services/Pick.php';

    // Allow Services_Exceptions to report as fault responses
    Zend_XmlRpc_Server_Fault::attachFaultException('Services_Exception');

    $server = new Zend_XmlRpc_Server();
    $server->setClass('Services_Comb', 'comb');   // methods called as comb.*
    $server->setClass('Services_Brush', 'brush'); // methods called as brush.*
    $server->setClass('Services_Pick', 'pick');   // methods called as pick.*

    // Create a request object
    $request = new Services_Request();

    // Utilize a custom response
    $server->setResponseClass('Services_Response');

    echo $server->handle($request);

### Cache server definitions between requests

The example below illustrates caching server definitions between requests.

    // Specify a cache file
    $cacheFile = dirname(__FILE__) . '/xmlrpc.cache';

    // Allow Services_Exceptions to report as fault responses
    Zend_XmlRpc_Server_Fault::attachFaultException('Services_Exception');

    $server = new Zend_XmlRpc_Server();

    // Attempt to retrieve server definition from cache
    if (!Zend_XmlRpc_Server_Cache::get($cacheFile, $server)) {
        $server->setClass('Services_Comb', 'comb');   // methods called as comb.*
        $server->setClass('Services_Brush', 'brush'); // methods called as brush.*
        $server->setClass('Services_Pick', 'pick');   // methods called as pick.*

        // Save cache
        Zend_XmlRpc_Server_Cache::save($cacheFile, $server);
    }

    // Create a request object
    $request = new Services_Request();

    // Utilize a custom response
    $server->setResponseClass('Services_Response');

    echo $server->handle($request);