Zend_XmlRpc_Server pretende ser un servidor XML-RPC completo, siguiendo las especificaciones descritas en www.xmlrpc.com. Además, implementa el método system.multicall(), permitiendo el empaquetado de peticiones (boxcarring).

Un ejemplo del caso de uso más básico:

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

Zend_XmlRpc_Server está compuesto por una variedad de componentes, que van desde el propio servidor hasta los objetos de petición, respuesta y fallo.

Para inicializar Zend_XmlRpc_Server, el desarrollador debe adjuntar una o más clases o funciones al servidor, mediante los métodos setClass() y addFunction().

Una vez hecho esto, puede pasar un objeto Zend_XmlRpc_Request a Zend_XmlRpc_Server::handle(), o de lo contrario se instanciará un objeto Zend_XmlRpc_Request_Http si no se proporciona ninguno -- obteniendo así la petición desde php://input.

Zend_XmlRpc_Server::handle() entonces intenta despachar hacia el manejador apropiado según el método solicitado. Luego devuelve ya sea un objeto basado en Zend_XmlRpc_Response o un objeto Zend_XmlRpc_Server_Fault. Estos objetos tienen ambos métodos __toString() que crean respuestas XML-RPC XML válidas, permitiendo que sean impresas directamente.

Zend_XmlRpc_Server permite al desarrollador adjuntar funciones y llamadas a métodos de clase como métodos XML-RPC despachables. Mediante Zend_Server_Reflection, realiza introspección sobre todos los métodos adjuntados, utilizando los docblocks de las funciones y métodos para determinar el texto de ayuda del método y las firmas del método.

Los tipos XML-RPC no necesariamente se corresponden uno a uno con los tipos de PHP. Sin embargo, el código hará lo posible por adivinar el tipo apropiado en función de los valores indicados en las líneas @param y @return. Algunos tipos XML-RPC no tienen un equivalente inmediato en PHP, sin embargo, y deben ser indicados mediante el tipo XML-RPC en el PHPDoc. Estos incluyen:

A continuación se muestra un ejemplo de cómo indicar estos tipos:

/**
* 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 no realiza ninguna validación de los tipos especificados para los parámetros o los valores de retorno, por lo que esto no tendrá ningún impacto en su documentación de la API. Sin embargo, proporcionar dichas indicaciones es necesario cuando el servidor valida los parámetros proporcionados a la llamada al método.

Es perfectamente válido especificar múltiples tipos tanto para los parámetros como para los valores de retorno; la especificación XML-RPC incluso sugiere que system.methodSignature debería devolver un array con todas las firmas de método posibles (es decir, todas las combinaciones posibles de valores de parámetros y de retorno). Puede hacerlo tal como lo haría normalmente con PhpDocumentor, utilizando el operador '|':

/**
* 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)
{
}

	Nota
	Permitir múltiples firmas puede generar confusión para los desarrolladores que utilizan los servicios; para simplificar las cosas, un método de servicio XML-RPC debería tener una única firma.

XML-RPC tiene un concepto de espacios de nombres; básicamente, permite agrupar métodos XML-RPC mediante espacios de nombres delimitados por puntos. Esto ayuda a evitar colisiones de nombres entre métodos servidos por distintas clases. Como ejemplo, se espera que el servidor XML-RPC sirva varios métodos en el espacio de nombres 'system':

Internamente, estos se corresponden con los métodos del mismo nombre en Zend_XmlRpc_Server.

Si desea añadir espacios de nombres a los métodos que sirve, simplemente proporcione un espacio de nombres al método correspondiente al adjuntar una función o clase:

// 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');

La mayoría de las veces, simplemente utilizará el tipo de petición predeterminado incluido con Zend_XmlRpc_Server, Zend_XmlRpc_Request_Http. Sin embargo, puede haber ocasiones en las que necesite que XML-RPC esté disponible a través de la CLI, una GUI, u otro entorno, o quiera registrar las peticiones entrantes. Para hacerlo, puede crear un objeto de petición personalizado que extienda Zend_XmlRpc_Request. Lo más importante que debe recordar es asegurarse de que los métodos getMethod() y getParams() estén implementados de forma que el servidor XML-RPC pueda recuperar esa información para despachar la petición.

De forma similar a los objetos de petición, Zend_XmlRpc_Server puede devolver objetos de respuesta personalizados; por defecto, se devuelve un objeto Zend_XmlRpc_Response_Http, que envía una cabecera HTTP Content-Type apropiada para su uso con XML-RPC. Posibles usos de un objeto personalizado serían registrar las respuestas, o enviar respuestas a STDOUT.

Para utilizar una clase de respuesta personalizada, use Zend_XmlRpc_Server::setResponseClass() antes de llamar a handle().

Zend_XmlRpc_Server captura las excepciones generadas por un método despachado, y genera una respuesta de fallo (fault) XML-RPC cuando se captura dicha excepción. Sin embargo, por defecto, los mensajes y códigos de excepción no se utilizan en una respuesta de fallo. Esta es una decisión intencionada para proteger su código; muchas excepciones exponen más información sobre el código o el entorno de la que un desarrollador necesariamente pretendería (un ejemplo típico son las excepciones de la capa de abstracción o de acceso a base de datos).

Sin embargo, las clases de excepción pueden incluirse en una lista blanca para usarse como respuestas de fallo. Para ello, simplemente utilice Zend_XmlRpc_Server_Fault::attachFaultException() para pasar una clase de excepción a incluir en la lista blanca:

Zend_XmlRpc_Server_Fault::attachFaultException('My_Project_Exception');

Si utiliza una clase de excepción de la que heredan las demás excepciones de su proyecto, puede entonces incluir en la lista blanca toda una familia de excepciones a la vez. Las excepciones de tipo Zend_XmlRpc_Server_Exception siempre están en la lista blanca, para permitir informar de errores internos específicos (métodos indefinidos, etc.).

Cualquier excepción que no esté específicamente en la lista blanca generará una respuesta de fallo con un código '404' y un mensaje 'Unknown error'.

Adjuntar muchas clases a una instancia del servidor XML-RPC puede utilizar muchos recursos; cada clase debe hacer introspección utilizando la API de Reflection (mediante Zend_Server_Reflection), lo que a su vez genera una lista de todas las posibles firmas de método para proporcionar a la clase del servidor.

Para reducir algo este impacto en el rendimiento, se puede utilizar Zend_XmlRpc_Server_Cache para almacenar en caché la definición del servidor entre peticiones. Cuando se combina con __autoload(), esto puede incrementar considerablemente el rendimiento.

A continuación se muestra un ejemplo de uso:

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();

El ejemplo anterior intenta recuperar una definición del servidor desde xmlrpc.cache en el mismo directorio que el script. Si no lo consigue, carga las clases de servicio que necesita, las adjunta a la instancia del servidor, y luego intenta crear un nuevo archivo de caché con la definición del servidor.

A continuación se muestran varios ejemplos de uso, que muestran todo el espectro de opciones disponibles para los desarrolladores. Los ejemplos de uso se irán construyendo cada uno sobre el ejemplo anterior proporcionado.

/**
 * 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();

require_once 'Services/Comb.php';

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

class Services_PricingService
{
    /**
     * Calculate current price of product with $productId
     *
     * @param ProductRepository $productRepository
     * @param PurchaseRepository $purchaseRepository
     * @param integer $productId
     */
    public function calculate(ProductRepository $productRepository,
                              PurchaseRepository $purchaseRepository,
                              $productId)
    {
        ...
    }
}

$server = new Zend_XmlRpc_Server();
$server->setClass('Services_PricingService',
                  'pricing',
                  new ProductRepository(),
                  new PurchaseRepository());

class Services_PricingService2
{
    /**
     * @param ProductRepository $productRepository
     * @param PurchaseRepository $purchaseRepository
     */
    public function __construct(ProductRepository $productRepository,
                                PurchaseRepository $purchaseRepository)
    {
        ...
    }

    /**
     * Calculate current price of product with $productId
     *
     * @param integer $productId
     * @return double
     */
    public function calculate($productId)
    {
        ...
    }
}

$server = new Zend_XmlRpc_Server();
$server->sendArgumentsToAllMethods(false);
$server->setClass('Services_PricingService2',
                  'pricing',
                  new ProductRepository(),
                  new PurchaseRepository());

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();

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();

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);

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);