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 starting with 0 and incremented by 1.

These functions reside in xmlrpc.inc.

php_xmlrpc_decode

mixedphp_xmlrpc_decode(xmlrpcval$xmlrpc_val,
 array$options);
 
arrayphp_xmlrpc_decode(xmlrpcmsg$xmlrpcmsg_val,
 string$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 are decode_php_objs and dates_as_objects. When the first 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). When the second is set, XML-RPC datetime values will be converted into native dateTime objects instead of strings.

WARNING: please take extreme care before enabling the decode_php_objs option: when php objects are rebuilt from the received xml, their constructor function will be silently invoked. This means that you are allowing the remote end to trigger execution of uncontrolled PHP code on your server, opening the door to code injection exploits. Only enable this option when you have complete trust of the remote server/client.

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" => ...
  )));

php_xmlrpc_encode

xmlrpcvalphp_xmlrpc_encode(mixed$phpval,
 array$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, null_extension 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). The second allows to encode php NULL values to the <NIL/> (or <EX:NIL/>, see ...) tag. The last encodes any string that matches the ISO8601 format into an XML-RPC datetime.

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

php_xmlrpc_decode_xml

xmlrpcval | xmlrpcresp | xmlrpcmsgphp_xmlrpc_decode_xml(string$xml,
 array$options);
 

Decodes the xml representation of either an xmlrpc request, response or single value, returning the corresponding php-xmlrpc object, or FALSE in case of an error.

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, no option is supported.

Example:


$text '<value><array><data><value>Hello world</value></data></array></value>';
$val php_xmlrpc_decode_xml($text);
if (
$val) echo 'Found a value of type '.$val->kindOf(); else echo 'Found invalid xml';