Using Serialized PHP with Yahoo! Web Services

Serialized PHP is a data encoding format for PHP. It is easy to store and transmit and is a convenient format for PHP developers to work with. It's built-in support in the PHP programming language makes it a good choice for PHP application developers.

Many of the Yahoo! Web Services provide Serialized PHP as an alternate output format to XML. This page describes The Yahoo! Web Services Serialized PHP output, and how to use it in your own programs. It contains these sections:

Serialized PHP Format Overview

Serialized PHP is a simple text format based on PHP's data structures. It is fully implemented in the PHP programming language by two built-in functions, serialize and unserialize. These two functions have been available in every PHP distribution since PHP 3.05.

A example of Serialized PHP returned by Yahoo! Web Services looks like this:

The general format of each Serialized PHP element is:

<data type>:<length>:<value>

Both element names and their values are serialized. So, in the sample above, the element totalResultsAvailable is prefixed by s:21. The s means that the identifier name is of type string and 21 is the number of characters in the identifier name totalResultsAvailable. The value of totalResultsAvailable is encoded as s:6:"266933", a string that's six characters long with the value "266933". Curly braces are used to enclose arrays and objects.

The possible Serialized PHP type identifiers for <data type> are:

  • a - array
  • b - boolean
  • d - double
  • i - integer
  • o - common object
  • r - reference
  • s - string
  • C - custom object
  • O - class
  • N - null
  • R - pointer reference
  • U - unicode string

To decode the Serialized PHP into PHP data structures, you apply PHP's unserialize function to the serialized data. Since Yahoo! Web Services uses associative and numerically indexed PHP arrays to represent web services responses, the results of deserialization will be PHP arrays. The result of applying the unserialize function to the serialized data above is listed in the box below.

Working With Serialized PHP

Using Serialized PHP with Yahoo! Web Services is straightforward, and, for PHP developers, easier than using XML.

Get Serialized PHP Output with output=php

By default, Yahoo! Web Services return output in XML format. Some, but not all, of the Yahoo! Web Services can also return Serialized PHP. To get output in Serialized PHP format, use the output=php parameter in the request:

http://search.yahooapis.com/ ImageSearchService/V1/ imageSearch?appid=YahooDemo &query=Madonna&results=1 &output=php

Serialized PHP versus XML

Both the XML and Serialized PHP output from the Yahoo! Web Services contain the same data; the only difference is in the format. The documentation on the Yahoo! Developer Network assumes XML output. Depending on the specific service you are using, there may be variations in how the XML output from the service maps onto the Serialized PHP notation, but in general you can assume these rules:

  • There will be one top level object containing the response (typically ResultSet).
  • Simple XML elements (elements that contain only content) become string/value pairs.
  • Complex XML elements (elements that contain nested elements) become nested objects.
  • Attributes become string/value pairs.
  • If an element contains both content and attributes, the attributes become string/value pairs and the content becomes a string/value pair with the name "content."
  • Repeated elements map onto arrays. The array is named after the element. The values of the array depend on the content of the repeated elements, that is, simple content becomes simple values, nested elements become objects. Note, however, that if a particular response that normally contains repeated element contains only one element you will not get an array of one element in the Serialized PHP-- the element is treated as if it were a simple complex XML element. For repeated elements you should ensure you test for an array or a scalar value.

The box below shows sample XML output. You can compare it to the Serialized PHP output displayed earlier on this page to see how Yahoo! Web Services encodes XML as PHP data structures.

Parsing Serialized PHP in your Scripts

Serialized PHP output can be easily parsed in PHP using the unserialize function:

// The Yahoo! Web Services request
$req = 'http://search.yahooapis.com/ ImageSearchService/V1/imageSearch? appid=YahooDemo&query=Madonna& results=1&output=php';
// Make the request
$phpserialized = file_get_contents($req);
// Parse the serialized response
$phparray = unserialize($phpserialized);

A complete code sample is available here.

Parsing Serialized PHP in Other Languages

Other programming languages can consume Serialized PHP using various 3rd party libraries. Here's a (probably incomplete) list:

For More Information

For more information on using PHP with Yahoo! Web Services APIs, see The Yahoo! Developer Network PHP Developer Center.