The xmlrpc extension contains a few functions that I consider general functionality. You can use them when creating either a client or a server as well as when creating a service not conforming to the XML-RPC specification. Many of these functions are useful when working manually with data, as you will see in the “Creating an XML-RPC Client” and “Creating an XML-RPC Server”
sections; in fact, you can use some quick and easy methods to implement XML-RPC.
Encoding and Decoding Data
You can encode and decode data similarly to how you do so using WDDX, as described in Chapter 15. The functions xmlrpc_encode()and xmlrpc_decode()can perform these opera- tions, but they do not generate a full XML-RPC request or response. They strictly handle the data and its types.
The xmlrpc_encode()function creates a paramsstructure. This in itself is not enough to make a request because the root methodCallelement is missing and because the correspon- ding methodNameis missing. For example:
$encoded = xmlrpc_encode(array(1, 2));
echo $encoded;
Calling this code creates a paramsstructure containing an array holding the values 1and 2:
<params>
<param>
<value>
<array>
<data>
<value><int>1</int></value>
<value><int>2</int></value>
</data>
</array>
</value>
</param>
</params>
Although not a complete request, the data can be converted to native PHP data types using the corresponding xmlrpc_decode()function:
$phpdata = xmlrpc_decode($encoded);
var_dump($phpdata);
array(2) { [0]=>
int(1) [1]=>
int(2) }
The question now becomes, why would you ever use these functions?
When making a request, you do not have any functions like when using wddx to build the XML document incrementally. It is an all-or-nothing deal. Although you could use DOM on the resulting paramsstructure and manually build a request document, you could use these functions to create a Web service that does not conform to the XML-RPC specification. You could pass the paramsstructure back and forth, between the client and the server, just like you pass a WDDX structure. No method name would be defined in the structure, but you could use a technology such as REST, covered in Chapter 17, for this purpose.
The xmlrpc_decode()function is a little more flexible. It decodes both full XML-RPC request documents, which are those containing the methodCalland methodNameelements, and those created by the xmlrpc_encode()function. The results from calling the function are the same regardless of the type of document being decoded. Any method information is dis- carded, and only the information contained within the paramselement is decoded.
Handling Non-Native PHP Data Types
The xmlrpc extension defines both a base64data type and a dateTime.iso8601data type, nei- ther of which is a native type in PHP. You can use the xmlrpc_set_type()and xmlrpc_get_type() functions to convert PHP data into these respective XML-RPC types and determine the type so they are compatible with the extension and can be used directly. You can use these functions when implementing either a client or a server so that the data is exchanged properly.
Consider the following piece of code that attempts to encode a date without setting its type:
$isodate = date('c');
echo xmlrpc_encode($isodate);
This simply results in a stringelement for the value:
<string>2005-10-19T12:24:42-04:00</string>
To the application reading this data, the data is simply a string and not identified as a date. Setting the type of the $isodatevariable to datetime, on the other hand, allows it to be encoded properly into a dateTime.iso8601type. For example:
$isodate = date('c');
xmlrpc_set_type($isodate, "datetime");
$encoded_iso = xmlrpc_encode($isodate);
echo $encoded_iso;
This time, the resulting content of the valueelement is as follows:
<dateTime.iso8601>20051019T12:38:16</dateTime.iso8601>
The base64data type is handled in the same manner. The variable being set by the xmlrpc_set_type()function will contain the raw binary data and the type base64passed as the type to the function. Upon encoding, not only will the base64element be used to hold the contents, but also the raw binary data is automatically Base64 encoded within the resulting structure.
■ Caution Using the xmlrpc_set_type()function to create datetimeand base64data types will con- vert the data type of any variable passed to the function into an object usable by the xmlrpc extension. This means trying to perform a function such as echoon the resulting variable will not work as expected.
When decoding an XML structure, unless absolutely positive that it does not contain adateTime.iso8601or base64type, you should check the type of variable. Any data of these types would be returned as objects. The values for these data types must be read through the object properties as follows:
xmlrpc_type: The data type set using xmlrpc_set_type().
scalar: The value for the data returned as a PHP string.
timestamp: This property is valid only for date/time data and is the value of the scalar in time-stamp format.
For example:
$phpdata = xmlrpc_decode($encoded_iso);
echo xmlrpc_get_type($phpdata)."\n\n";
var_dump($phpdata);
Using the $encoded_isovariable from the previous example, the data is decoded, the type is output, and the resulting PHP data is output using the var_dump()function:
datetime
object(stdClass)#2 (3) { ["scalar"]=>
string(17) "20051019T13:21:40"
["xmlrpc_type"]=>
string(8) "datetime"
["timestamp"]=>
int(1129742500) }