2. Easy use with nested PHP values

Dan Libby was kind enough to contribute two helper functions that make it easier to translate to and from PHP values. This makes it easier to deal with complex structures. At the moment support is limited to int, double, string, array, datetime and struct datatypes; note also that all PHP arrays are encoded as structs, except arrays whose keys are integer numbers staring with 0 and incremented by 1.

These functions reside in xmlrpc.inc.

2.1. php_xmlrpc_decode

$phpval = php_xmlrpc_decode($xmlrpc_val$options); 
,  $xmlrpc_val$options, ;
$phpvals = php_xmlrpc_decode($xmlrpcmsg_val$options); 
,  $xmlrpcmsg_val$options, ;

Returns a native PHP value corresponding to the values found in the xmlrpcval $xmlrpc_val, translated into PHP types. Base-64 and datetime values are automatically decoded to strings.

In the second form, returns an array containing the parameters of the given xmlrpcmsg_val, decoded to php types.

The options parameter is optional. If specified, it must consist of an array of options to be enabled in the decoding process. At the moment the only valid option is decode_php_objs. When it is set, php objects that have been converted to xml-rpc structs using the php_xmlrpc_encode function and a corresponding encoding option will be converted back into object values instead of arrays (provided that the class definition is available at reconstruction time).

Example:

// wrapper to expose an existing php function as xmlrpc method handler
function foo_wrapper($m)
{
  $params = php_xmlrpc_decode($m);
  $retval = call_user_func_array('foo', $params);
  return new xmlrpcresp(new xmlrpcval($retval)); // foo return value will be serialized as string
}

$s = new xmlrpc_server(array(
   "examples.myFunc1" => array(
     "function" => "foo_wrapper",
     "signatures" => ...
  )));

2.2. php_xmlrpc_encode

$xmlrpc_val = php_xmlrpc_encode($phpval,  
 $options); 
 $phpval;
 $options;

Returns an xmlrpcval object populated with the PHP values in $phpval. Works recursively on arrays and objects, encoding numerically indexed php arrays into array-type xmlrpcval objects and non numerically indexed php arrays into struct-type xmlrpcval objects. Php objects are encoded into struct-type xmlrpcvals, excepted for php values that are already instances of the xmlrpcval class or descendants thereof, which will not be further encoded. Note that there's no support for encoding php values into base-64 values. Encoding of date-times is optionally carried on on php strings with the correct format.

The options parameter is optional. If specified, it must consist of an array of options to be enabled in the encoding process. At the moment the only valid options are encode_php_objs and auto_dates.

The first will enable the creation of 'particular' xmlrpcval objects out of php objects, that add a "php_class" xml attribute to their serialized representation. This attribute allows the function php_xmlrpc_decode to rebuild the native php objects (provided that the same class definition exists on both sides of the communication)

Example:

// the easy way to build a complex xml-rpc struct, showing nested base64 value and datetime values
$val = php_xmlrpc_encode(array(
  'first struct_element: an int' => 666,
  'second: an array' => array ('apple', 'orange', 'banana'),
  'third: a base64 element' => new xmlrpcval('hello world', 'base64'),
  'fourth: a datetime' => '20060107T01:53:00'
  ), array('auto_dates'));