When the wddx extension is unavailable or for some reason you just don’t want to use it, you can use the PEAR XML_WDDX package to serialize and unserialize WDDX packets. It is com- patible with PHP 5 and newer, so it will work correctly when migrating code from PHP 4 that might have used this package. Although XML_WDDX will use the wddx_deserialize()func- tion if the wddx extension is available, this package is not an exact replacement for the extension, as you will see in this section.
You can install the package by using the PEAR installer. (You can find additional informa- tion about PEAR and its installer in Chapter 13.)
pear install XML_WDDX
At the time of this writing, the current stable release is 1.0.1, and the only dependency is the xml extension. When the wddx extension is present on the system, it is leveraged by XML_Wddx to unserialize packets. Once you have installed the package, you can use the XML_Wddxclass within your script by adding the appropriate requirestatement:
require 'XML/Wddx.php';
The class is then instantiated using the newkeyword. You don’t have to pass any parame- ters to the constructor, so the call is simply as follows:
$objWddx = new XML_Wddx();
XML_Wddxprovides only two public methods: serialize()and deserialize(). The serialize()method works just like the wddx_serialize_value()function from the wddx extension. It accepts only a single parameter that contains the data to be serialized. It does not provide any mechanism for creating a comment but does create and return the entire packet from the method call.
■ Note Control characters within strings are not handled using charelements. Any string that contains a control character, explained in the earlier “string” section, is encapsulated within a CDATA section. To clarify this, the entire string, and not just the control characters, is encapsulated.
You can unserialize a packet using the deserialize()method. This method takes one parameter containing the packet and returns the unserialized data as a native PHP data type.
How the packet is unserialized depends upon whether the wddx extension was installed with PHP. When present, the wddx_deserialize()method is used when the XML_Wddx deserialize() method is called; otherwise, the native XML_Wddxcode is used. This impacts unserialization because the wddx extension provides support for more data types and XML_Wddx. The following is a list of some of the differences between the two:
• XML_Wddxdoes not handle a recordsetelement.
• XML_Wddxdoes not handle a dateTimeelement.
• The wddx extension Base64 decodes the contents of binary elements and returns the actual binary data. XML_Wddxdoes not, and the data is returned as a Base64-encoded string that the user must decode.
For example:
<?php
/* Require the XML_Wddx package */
require 'XML/Wddx.php';
/* Some variables to pass */
$myinteger = 1;
$mystring = 'My String';
$mysecondstring = "Second\nString";
$myarray = array('a', 'b', 'c');
$mystruct = array('key1'=>'a', 'key2'=>'b', 'key3'=>'c');
/* Multiple variables must be passed within an array */
$myvalues = array($myinteger, $mystring, $mysecondstring, $myarray, $mystruct);
$objWddx = new XML_Wddx();
echo $objWddx->serialize($myvalues);
?>
The output of this script should look a bit familiar to you. The same variables were serial- ized in Listing 15-2 using the wddx extension. The output has a few noticeable differences, however.
<wddxPacket version='1.0'><header/><data>
<array length='5'>
<number>1</number>
<string>My String</string>
<string><![CDATA[Second String]]></string>
<array length='3'>
<string>a</string>
<string>b</string>
<string>c</string>
</array>
<struct>
<var name='key1'><string>a</string></var>
<var name='key2'><string>b</string></var>
<var name='key3'><string>c</string></var>
</struct>
</array>
</data></wddxPacket>
The first thing you will notice is that this code uses an arrayelement rather than a struct element as the child for the dataelement. XML_Wddxdoes not accept multiple variables for seri- alization; thus, you must place them in an array that is then serialized. Because they are passed by array and no key is specified, varelements are not created. The other noticeable difference is the use of the CDATA section within the second stringelement. The wddx extension does not use CDATA sections but rather escapes the characters <, &, and >, and it converts control char- acters to charelements.
XML_Wddx, however, does understand charelements during deserialization. The output from the deserialization()method depends upon whether the wddx extension has been installed with PHP. When it exists, the XML_Wddx deserialization()method natively uses it;
otherwise, the built-in deserialization routine is used. The following example uses the data from $serialized_outin Listing 15-2:
require 'XML/Wddx.php';
$objWddx = new XML_Wddx();
/* $serialized_out is the resulting serialized data from Listing 15-2. */
$arRet = $objWddx->deserialize($serialized_out);
var_dump($arRet);
The following is the resulting data structure from the var_dump()call. Remember, this output is based on that the wddx extension was not installed with PHP and the internal deserialization routine from the XML_Wddxclass is being used. If you are trying this code on a machine that has the wddx extension installed, your output will be the same as the output in Listing 15-3.
array(5) { ["myinteger"]=>
string(1) "1"
["mystring"]=>
string(9) "My String"
["mysecondstring"]=>
string(13) "Second String"
["myarray"]=>
array(3) { [0]=>
string(1) "a"
[1]=>
string(1) "b"
[2]=>
string(1) "c"
}
["mystruct"]=>
array(3) { ["key1"]=>
string(1) "a"
["key2"]=>
string(1) "b"
["key3"]=>
string(1) "c"
} }
Conclusion
WDDX is an XML format that allows data and its corresponding data types to be exchanged between two independent systems. It is platform agnostic and supported through a number of languages. Although not a Web service on its own, it can be used to create Web services, and its format is much simpler than a SOAP document. It never became as much of a buzzword as SOAP, but it provides a quick and easily created format that can be leveraged when needing to connect systems.
This chapter dissected the WDDX structure and covered how both the wddx extension and the XML_Wddxclass can create WDDX documents. Within the examples, you learned how to create a simple Web service using WDDX as the data envelope.
The next chapter progresses further into the area of Web services with a discussion of XML-RPC. Unlike WDDX, XML-RPC is a complete service that includes how the data is trans- ported between systems.