Xenophobia XML-RPC library manual

XMLRPCServer XMLRPCServer::__construct ( void )

Once the server is instantiated it will have a number of "system" procedures, but will not serve incoming requests unless told to do so:

void XMLRPCServer::serve ( void )

At this point the server will process requests, but a server composed of only the basic system procedures doesn't do much. Procedure calls should first be added:

bool XMLRPCServer::addCall ( string name, callback callback [, array signature [, string help]] )

Above, name is an identifier for use by clients (eg. system.listMethods, math.sqRoot), callback is a callback as described in Ch.11, §10 of the PHP manual. Signature is a method signature as described by the original implementation: the array's first member is the return type; subsequent members are the types of required arguments. Finally, help is a human-readable, freeform description of the method.

Note that a method may have several signatures, but addCall only accepts one. Additional signatures may be defined with addSignature:

bool XMLRPCServer::addSignature ( string call, array signature )

If call is not yet defined, the method will return FALSE.

Below are some simple examples of server usage:

<?php
// Implementing the familiar PHP "implode" function as an RPC
$server = new XMLRPCServer();
$server->addCall("string.concat", "implode", array("string", "array"), "Takes an array of strings (optionally with a 'glue' string) and returns a concatenation.");
$server->addSignature("string.concat", array("string", "string", "array"));
$server->serve();

<?php
// Implementing something similar to the above

// First have a callback, in this case a function
function xmlrpc_concat()
 {$args = func_get_args();
  if (sizeof($args)==1 && is_array($args[0]))
   {return implode("", $args[0]);}
  elseif (sizeof($args) < 2)
   {return new XMLRPCException("No strings to concatenate", 0);}
  else
   {return implode("", $args);}
 }

//Now start the server
$server = new XMLRPCServer();
$server->addCall("string.concat", "xmlrpc_concat", array("string", "array"), "Takes an array of strings or a variable number of strings and concatenates them.");
$server->addSignature("string.concat", array("string", "string", "string"));
$server->serve();

Catching exceptions and errors

The Xenophobia server sends its reply by outputting as any other PHP script with echo. Because of this, printed error messages will usually cause the server to send malformed XML to clients.

To prevent this, one may set PHP to report no errors (by using error_reporting(0)), but this has the disadvantage of giving no indication when an unforeseen, possibly serious problem has occured with the server. Xenophobia provides a more elegant solution: the static method XMLRPCServer::handleErrors().

This method, which can be called as soon as the library is included, reports any errors or uncaught exceptions that would normally be printed as an XML-RPC fault. Note, however, that when using this method all errors within the error-reporting threshold are considered fatal. Parse errors and the like, of course, cannot be caught by this facility.

Below is a simplistic example of how this works:

<?php
XMLRPCServer::handleErrors();                       //hand off error handling
$document = DOMDocument::loadXML("<malformedXML>"); //try to parse bad XML; this would print warnings

// The server will respond with this message (formatted here for readability):
/*
<?xml version="1.0"?>
<!--
This message is an XML-RPC server response, generated due to an error in
the script automating this server.  If you were expecting something other
than an XML-RPC response, the error is likely beyond your control.
-->
<methodResponse><fault><value>
 <struct>
  <member>
   <name>faultCode</name>
   <value><int>-32500</int></value>
  </member>
  <member>
   <name>faultString</name>
   <value><string>DOMDocument::loadXML(): Premature end of data in tag malformedXML line 1 in Entity, line: 1 (PHP code: 2)</string></value>
  </member>
 </struct>
</value></fault></methodResponse>
*/

Adding capabilities

Server capabilities (which can be enumerated with the procedure call system.getCapabilities) are an advisory list of what the server can do. Typically, this is a list of specifications which the given server adheres to. The list of capabilities for a base Xenophobia server is provided in brief in the preface.

To add a capability, the method XMLRPCServer::addCapability() is used:

bool XMLRPCServer::addCapability ( string name, string spec_url, int spec_version )

name is an arbitrary name for the capability, sometimes provided by specifications, but often not. spec_url is a URL to the specification of the given capability, and spec_version is an integer version number for the specification; ideally this should be a revision date in YYYYMMDD form, but exact revision dates are sometimes difficult to ascertain.

Herewith an example, adding a capability for "Pingback":

<?php
$server = new XMLRPCServer();
$server->addCapability("pingback", "http://www.hixie.ch/specs/pingback/pingback", 20070114);
$server->serve();

Server self-test

As a convenience to both users and authors and as a reasonably complete test of the Xenophobia library, HTTP GET requests to a Xenophobia server will present a nicely-formatted HTML document containing a list of capabilities and procedure calls implemented by that particular server.

This list acts as a fairly complete test of the library since the server queries itself with a client: all data about the server is retrieve via RPCs, and the following functions are tested:

• The client calls system.getCapabilities
• The client calls system.listMethods
• The client calls system.methodSignature and system.methodHelp multiple times using system.multicall

As this document is presented once XMLRPCServer::serve() is called, the list of capabilities and procedure calls should always be accurate.

Using the Xenophobia client is quite simple. First a client instance must be created:

XMLRPCClient XMLRPCClient::__construct ( string server_url )

The server_url must be an absolute URL to an XML-RPC server. Explicit credentials or port number are allowed.

Once a server has been specified the client can then perform an unlimited number of procedure calls with the XMLRPCClient::call() method:

mixed XMLRPCClient::call ( string call [, mixed parameter... ] )

When using this method, the call and zero or more parameters are sent to the server for processing. The server's reply is then returned, whether it be the expected result or an XML-RPC fault.

It is the responsibility of the user to ensure that the data type of each parameter matches what the server expects. Although the Xenophobia server will gladly accept values that are of a different type thanks to PHP's type juggling, other servers may fail in this case.

Below is an example of the client's use.

<?php
// retrieve the current time from UserLand's time server
$client = new XMLRPCClient("http://time.xml-rpc.com/RPC2");
$result = $client->call("currentTime.getCurrentTime"); //returns a "DateTime" object
echo $result->format("r");

/* prints, for example:

Fri, 02 Feb 2007 14:49:17 -0500

*/

Multicall

system.multicall is a procedure call that allows a client to perform an arbitrary number of calls with a single request. This has the advantage of reducing HTTP traffic, and cutting down the time and processing power needed to perform multiple requests.

Xenophobia implements system.multicall thus: First, procedure calls must be added to a queue:

bool XMLRPCClient::addCall ( string call [, mixed parameter...] )

Once all desired calls are queued, the multicall itself is executed:

array XMLRPCClient::call ( void )

Returned is an array of values, one for each call in the queue. If the XMLRPCClient::call() method is passed parameters while there are calls in the queue, the specified call bypasses the queue entirely and is executed immediately.

The queue is cleared whenever a multicall is performed, but it can also be cleared explicitly:

void XMLRPCClient::clear ( void )

Note that system.multicall can also be used like any other procedure call. This is especially useful to test whether a server implements it.

Xenophobia has a small number of public properties used for configuration purposes. Of these, only two---both static properties---are not properties of the XMLRPCServer or XMLRPCClient classes:

XMLRPCLib::$useNil

This static property is used by both the server and the client to decide whether to use the explicit nil element when sending messages. This property is set to FALSE by default; in this case the library will use an empty value element in its messages. Note that neither of these two behaviours are standard: other clients and servers may refuse messages containing either implicit or explicit NULL values.

XMLRPCLib::$schema

This static property contains the RELAX NG schema (in XML form) used by Xenophobia when validating messages.

XMLRPCServer::$useSchema

This property sets whether the server should validate incoming messages using the library's RELAX NG schema. It defaults to TRUE.

XMLRPCServer::$inputSource

This property defines the stream URI from which the server will pull the incoming message. Set to php://input by default, it should be changed only for debugging purposes. Changing this property disables both the server's GET self-test and Content-Type checking. See also Appendix M of the PHP manual for information on possible values.

XMLRPCClient::$useSchema

This property sets whether the client should validate incoming messages using the library's RELAX NG schema. It defaults to TRUE.

XMLRPCClient::$useCurl

This property sets whether the clint should should try using cURL (if available) to send its messages before falling back to using the HTTP stream wrapper. It is TRUE by default.

XMLRPCClient::$debug

This property sets the client in debug mode. In this mode any call will return, instead of the response data, an array with the keys request and response, which will contain the serialized XML data sent to and received from the server respectively. No validation will be done on the response. If using cURL the HTTP header is included with the reponse. This property is set to FALSE by default.

XMLRPCClient::$throw

This property sets whether the client will throw XML-RPC faults as exceptions instead of returning them as with other values. The default is FALSE.

XML-RPC faults are somewhat analogous to PHP exceptions; consequently faults are implemented as exceptions via the class XMLRPCException. This class functions exactly as a typical exception would.

When a procedure call on the server needs to return a fault, an XMLRPCException instance can be either returned or thrown: in either case the server will capture it and convert it to the proper XML structure. When the client receives or produces a fault, it will be returned; exceptions are thrown only if the client is configured to do so. See §2.3 for details.

XML-RPC has two compound types: arrays and structs. Unlike in PHP, XML-RPC arrays are only a collection of values; no keys are stored. Instead, structs are used when key preservation is desired. This, however, presents a problem when converting a PHP array: is it an array or a struct? Xenophobia answers this question using a fairly simple algorithm:

If every key, after being cast as an integer, is loosely equivalent to the original key, the array is an XML-RPC array; otherwise it is a struct. Whether the numeric keys are contiguous or even in order is irrelevant: the array is simply iterated with foreach and each key is compared. The values are then constructed into an XML-RPC array in the order in which they were found. Is it up to the user to sort array keys beforehand if desired.

Note also that an empty array is considered an XML-RPC array. If an empty struct is required, an object with no public properties should be used instead, as objects are always converted into structs.

Although a PHP object is considered to be equivalent to a struct, an XML-RPC struct is always converted into an associative array.

XML-RPC has no null type. As such, using NULL when formulating a request or response should be avoided.

Nevertheless Xenophobia is capable of dealing with implicit null values and the non-standard explicit nil element. A value in an XML-RPC message is considered to be null if the value element contains no child elements or contains a nil element. No other conditions will produce NULL. Unknown values in an XML-RPC message produce an XMLRPCUnknownValue object.

When constructing a message, NULL will be represented by an empty value element unless the library is configured to send nil elements. See §2.1 for details. PHP types with no XML-RPC analogue (such as resources) produce an empty string element.

PHP has no native type for dates as such, but PHP 5.2 introduces a DateTime class, which Xenophobia uses in lieu of something else. When running on versions of PHP prior to 5.2, the DateTime class is emulated with a PHP class that replicates the same basic functionality. The companion DateTimeZone class is not emulated, since XML-RPC is ambiguous as to timezone handling.

Unfortunately the PHP manual has, as of this writing, no useful documentation on the DateTime class---probably because it is still primitive and inconsistent. Worse, what documentation there is is apparently inaccurate. Therefore, the class should probably only be used for extracting the current date or time with the format method. Still, since there are no better options, below is a table summarizing the emulated class' methods. It has no public properties.

Although PHP has adequate facilities for dealing with base64-encoded strings, there is no way to disambiguate between a string that is encoded and one that is not. Therefore, when wishing to send a base64-encoded string in a request or response, one must use the XMLRPCBase64 class directly:

XMLRPCBase64 XMLRPCBase64::__construct ( string data )

Base64-encoded data received in a message is automatically decoded and provided as a string, however.