24.3. Zend_XmlRpc_Server

24.3.1. Wprowadzenie

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.

24.3.2. Podstawowe użycie

Przykład najbardziej podstawowego przypadku użycia:

<?php
require_once 'Zend/XmlRpc/Server.php';
require_once 'My/Service/Class.php';

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

24.3.3. Struktura serwera

Zend_XmlRpc_Server składa się z wielu różnych komponentów, ranging from the server itself to request, response, and fault objects.

Aby uruchomić serwer Zend_XmlRpc_Server, programista musi dołączyć jedną lub więcej klas albo funkcji do serwera, za pomocą metod setClass() oraz addFunction().

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_Faultobject. These objects both have __toString() methods that create valid XML-RPC XML responses, allowing them to be directly echoed.

24.3.4. Konwencje

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ńcuch znaków sformatowany jako YYYYMMDDTHH:mm:ss

  • base64, dane zakodowane jako base64

  • struct, dowolna tablica asocjacyjna

Przykład wywołania przykładowej funkcji:

<?php
/**
* To jest przykładowa funkcja
*
* @param base64 $val1 Dane zakodowane jako Base64
* @param dateTime.iso8601 $val2 Data ISO
* @param struct $val3 Tablica asocjacyjna
* @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:

<?php
/**
* To jest przykładowa funkcja
*
* @param string|base64 $val1 Łańcuch znaków lub dane zakodowane jako base64
* @param string|dateTime.iso8601 $val2 Łańcuch znaków lub data ISO
* @param array|struct $val3 Normalnie indeksowana tablica lub tablica asocjacyjna
* @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.

24.3.5. Używanie przestrzeni nazw

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:

<?php
// Wszystkie publiczne metody klasy My_Service_Class będą dostępne jako
// myservice.METHODNAME
$server->setClass('My_Service_Class', 'myservice');

// Funkcja 'somefunc' będzie dostępna jako funcs.somefunc
$server->addFunction('somefunc', 'funcs');

24.3.6. Własny obiekt żądania

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.

24.3.7. Własne odpowiedzi

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.

Aby użyć własnej klasy odpowiedzi, użyj metody Zend_XmlRpc_Server::setResponseClass() przed wywołaniem handle().

24.3.8. 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:

<?php
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_Exceptions 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'.

24.3.9. Buforowanie definicji serwera pomiędzy żądaniami

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.

Przykładowe użycie:

<?php
require_once 'Zend.php';
require_once 'Zend/XmlRpc/Server.php';
require_once 'Zend/XmlRpc/Server/Cache.php';

function __autoload($class)
{
    Zend::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');   // przestrzeń nazwa glue
    $server->setClass('My_Services_Paste', 'paste'); // przestrzeń nazwa paste
    $server->setClass('My_Services_Tape', 'tape');   // przestrzeń nazwa tape

    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.

24.3.10. Przykład użycia

Poniżej znajduje się kilka przykładów użycia, pokazując pełne spektrum opcji dostępnych dla programistów. Każdy z przykładów użycia jest oparty na poprzednich przykładach.

24.3.10.1. Podstawowe użycie

Poniższy przykład dołącza funkcję jaką uruchamialną przez XML-RPC metodę i obsługuje przychodzące wywołania.

<?php
require_once 'Zend/XmlRpc/Server.php';

/**
 * Zwraca sumę MD5 zadanej wartości
 *
 * @param string $value wartość do obliczenia sumy md5
 * @return string MD5 suma wartości
 */
function md5Value($value)
{
    return md5($value);
}

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

24.3.10.2. Dołączanie klasy

Poniższy przykład pokazuje dołączanie publicznych metod klasy jako uruchamialnych metod XML-RPC.

<?php
require_once 'Zend/XmlRpc/Server.php';
require_once 'Services/Comb.php';

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

24.3.10.3. Dołączanie wielu klas używając przestrzeni nazw

Poniższy przykład pokazuje dołączanie kilku klas, każdej z własną przestrzenią nazw.

<?php
require_once 'Zend/XmlRpc/Server.php';
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');   // metody wywoływane jako comb.*
$server->setClass('Services_Brush', 'brush'); // metody wywoływane jako brush.*
$server->setClass('Services_Pick', 'pick');   // metody wywoływane jako pick.*
echo $server->handle();

24.3.10.4. 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.

<?php
require_once 'Zend/XmlRpc/Server.php';
require_once 'Zend/XmlRpc/Server/Fault.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');   // metody wywoływane jako comb.*
$server->setClass('Services_Brush', 'brush'); // metody wywoływane jako brush.*
$server->setClass('Services_Pick', 'pick');   // metody wywoływane jako pick.*
echo $server->handle();

24.3.10.5. Utilizing a custom request object

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

<?php
require_once 'Zend/XmlRpc/Server.php';
require_once 'Zend/XmlRpc/Server/Fault.php';
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');   // metody wywoływane jako comb.*
$server->setClass('Services_Brush', 'brush'); // metody wywoływane jako brush.*
$server->setClass('Services_Pick', 'pick');   // metody wywoływane jako pick.*

// Tworzenie obiektu żądania
$request = new Services_Request();

echo $server->handle($request);

24.3.10.6. Utilizing a custom response object

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

<?php
require_once 'Zend/XmlRpc/Server.php';
require_once 'Zend/XmlRpc/Server/Fault.php';
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');   // metody wywoływane jako comb.*
$server->setClass('Services_Brush', 'brush'); // metody wywoływane jako brush.*
$server->setClass('Services_Pick', 'pick');   // metody wywoływane jako pick.*

// Utwórz obiekt żądania
$request = new Services_Request();

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

echo $server->handle($request);

24.3.10.7. Cache server definitions between requests

Poniższy przykład pokazuje buforowanie definicji serwera pomiędzy żądaniami.

<?php
require_once 'Zend/XmlRpc/Server.php';
require_once 'Zend/XmlRpc/Server/Fault.php';
require_once 'Zend/XmlRpc/Server/Cache.php';
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';

// Określ plik cache
$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();

// Spróbuj pobrać definicje serwera z bufora
if (!Zend_XmlRpc_Server_Cache::get($cacheFile, $server)) {
    $server->setClass('Services_Comb', 'comb');   // metody wywoływane jako comb.*
    $server->setClass('Services_Brush', 'brush'); // metody wywoływane jako brush.*
    $server->setClass('Services_Pick', 'pick');   // metody wywoływane jako pick.*

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

// Utwórz obiekt żądania
$request = new Services_Request();

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

echo $server->handle($request);