2. Easy use with nested PHP values
Prev | Chapter 9. Helper functions | Next

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

These functions reside in `xmlrpc.inc`.

### 2.1. php_xmlrpc_decode

`$phpval = php_xmlrpc_decode(` | $xmlrpc_val, |
| $options`)`; |

`xmlrpcval` | `$xmlrpc_val;`
`array` | `$options;`

`$phpvals = php_xmlrpc_decode(` | $xmlrpcmsg_val, |
| $options`)`; |

`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 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).

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

### 2.2. php_xmlrpc_encode

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

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

### 2.3. php_xmlrpc_decode_xml

`$xmlrpc_obj = php_xmlrpc_encode_xml(` | $xml, |
| $options`)`; |

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

Prev | Up | Next
1. Date functions | Home | 3. Automatic conversion of php functions into xmlrpc methods (and vice versa)