XML-RPC Types

Supported types

XRL supports all the datatypes defined in the official XML-RPC specification, namely:

  • int and i4: 32-bit signed integer value
  • boolean: your usual boolean type
  • string: regular string
  • double: double-precision signed floating point number
  • dateTime.iso8601: date/time (without milliseconds/timezone information)
  • base64: base64-encoded binary string
  • struct: associative array
  • array: numeric array

It also accepts the following types, which are pretty common, despite them not being part of the official specification:

  • nil: null value
  • i8: 64-bit signed integer value

Last but not least, it supports the following namespaced types, defined by the Apache Foundation. Please note that in this particular case, the types must belong to the namespace URI http://ws.apache.org/xmlrpc/namespaces/extensions to be correctly interpreted.

  • nil: null value (same as the non-namespaced type)
  • i1: 8-bit signed integer value
  • i2: 16-bit signed integer value
  • i8: 64-bits signed integer value (same as the non-namespaced type)
  • biginteger: arbitrary-length integer
  • dom: a DOM node, transmitted as an XML fragment
  • dateTime: date/time with milliseconds and timezone information

When transmitting non-standard types, XRL always uses namespaced types. See the next chapter for more information.

Type conversions

By default, XRL automatically converts values between PHP & XML-RPC types where appropriate.

The following table shows how XRL converts PHP types to XML-RPC types.

PHP to XML-RPC conversion
PHP type XML-RPC type
null namespaced nil
boolean boolean
integer i4 if it fits into 32 bits, namespaced i8 [1] otherwise
double double
string string if it is a valid UTF-8 string, base64 otherwise
array array for numeric arrays, struct for associative arrays
GMP integer resource (PHP < 5.6.0) i4 if it fits into 32 bits, namespaced i8 [1] if it fits into 64 bits, namespaced biginteger [1] otherwise
\GMP object (PHP >= 5.6.0) i4 if it fits into 32 bits, namespaced i8 [1] if it fits into 64 bits, namespaced biginteger [1] otherwise
\fpoirotte\XRL\Types\AbstractType object XML-RPC type it represents
\DateTime object

dateTime.iso8601 .. note:

The XML-RPC ``dateTime.iso8601`` data type does not support
milliseconds, nor passing timezone information.
Only use this type when the actual timezone is known beforehand
(using contextual information or a pre-established convention),
or when potential errors in date/time handling are not an issue.
\DOMNode object namespaced dom [1]
\XMLWriter object namespaced dom [1]
\SimpleXMLElement object namespaced dom [1]
\Exception object XML-RPC fault (derived from struct)

The following table shows how XRL converts XML-RPC types to PHP types.

XML-RPC to PHP conversion
XML-RPC type PHP type
boolean boolean
i4 integer
int integer
double double
string string
base64 string
array numeric array
struct \Exception object if the structure represents a fault [2], associative array otherwise
dateTime.iso8601 \DateTime (using local timezone information by default)
nil null
namespaced nil [1] null
namespaced i1 [1] integer
namespaced i2 [1] integer
i8

integer on 64-bit PHP, a GMP integer resource (on PHP < 5.6.0) or a \GMP object (on PHP >= 5.6.0) .. note:

An exception will be thrown in this case if PHP's native
``integer`` type cannot be used and the GMP extension
is not available.
namespaced i8 [1]

integer on 64-bit PHP, either a GMP integer resource (on PHP < 5.6.0) or a \GMP object (on PHP >= 5.6.0) .. note:

An exception will be thrown in this case if PHP's native
``integer`` type cannot be used and the GMP extension
is not available.

otherwise (the GMP extension is required in this case)
namespaced biginteger [1]

GMP integer resource (PHP < 5.6.0) or \GMP object (PHP >= 5.6.0) .. note:

An exception will be thrown in this case if the GMP extension
is not available.
namespaced dom [1] \SimpleXMLElement object
namespaced datetime [1] \DateTime object (using local timezone information by default, but can be configured to use another timezone as well)
[1](1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15) Using the namespace URI http://ws.apache.org/xmlrpc/namespaces/extensions for compatibility with other implementations.
[2]An XML-RPC struct representing a fault (ie. an error condition) gets converted to an exception that is automatically thrown.

Under the hood

Type conversions are handled by the \fpoirotte\XRL\NativeEncoder class (for PHP to XML-RPC conversions) and \fpoirotte\XRL\NativeDecoder class (for XML-RPC to PHP conversions), with support from classes in the \fpoirotte\XRL\Types\ namespace.

You may override or disable the conversion by passing another encoder/decoder to the XML-RPC client or server constructor.

Note

If you change the default encoder/decoder, you will then be responsible for handling conversions to/from the \fpoirotte\XRL\Types\AbstractType instances XRL uses internally.

Warning

XML-RPC faults are handled specially and will always turn into \fpoirotte\XRL\Exception objects that get raised automatically, no matter what decoder has been passed to the client/server’s constructor.