Lightning Guide to XML

Most XML consists of elements (like HTML tags), entities, and regular data. For example:

<book isbn="1-56592-610-2">
 <title>Programming PHP</title>
 <authors>
 <author>Rasmus Lerdorf</author>
 <author>Kevin Tatroe</author>
 <author>Peter MacIntyre</author>
 </authors>
</book>

In HTML, you often have an open tag without a close tag. The most common example of this is:

<br>

In XML, that is illegal. XML requires that every open tag be closed. For tags that don’t enclose anything, such as the line break <br>, XML adds this syntax:

<br />

Tags can be nested but cannot overlap. For example, this is valid:

<book><title>Programming PHP</title></book>

This, however, is not valid, because the <book> and <title> tags overlap:

<book><title>Programming PHP</book></title>

XML also requires that the document begin with a processing instruction that identifies the version of XML being used (and possibly other things, such as the text encoding used). For example:

<?xml version="1.0" ?>

The final requirement of a well-formed XML document is that there be only one element at the top level of the file. For example, this is well formed:

<?xml version="1.0" ?>
<library>
 <title>Programming PHP</title>
 <title>Programming Perl</title>
 <title>Programming C#</title>
</library>

This is not well formed, as there are three elements at the top level of the file:

<?xml version="1.0" ?>
<title>Programming PHP</title>
<title>Programming Perl</title>
<title>Programming C#</title>

XML documents generally are not completely ad hoc. The specific tags, attributes, and entities in an XML document, and the rules governing how they nest, compose the structure of the document. There are two ways to write down this structure: the document type definition (DTD) and the schema. DTDs and schemas are used to validate documents—that is, to ensure that they follow the rules for their type of document.

Most XML documents don’t include a DTD; in these cases, the document is considered valid merely if it’s valid XML. Others identify the DTD as an external entity with a line that gives the name and location (file or URL) of the DTD:

<!DOCTYPE rss PUBLIC 'My DTD Identifier' 'http://www.example.com/my.dtd'>

Sometimes it’s convenient to encapsulate one XML document in another. For example, an XML document representing a mail message might have an attachment element that surrounds an attached file. If the attached file is XML, it’s a nested XML document. What if the mail message document has a body element (the subject of the message), and the attached file is an XML representation of a dissection that also has a body element, but this element has completely different DTD rules? How can you possibly validate or make sense of the document if the meaning of body changes partway through?

This problem is solved with the use of namespaces. Namespaces let you qualify the XML tag—for example, email:body and human:body.

There’s a lot more to XML than we have time to go into here. For a gentle introduction to XML, read Learning XML (http://oreil.ly/Learning_XML) by Erik Ray (O’Reilly). For a complete reference to XML syntax and standards, see XML in a Nutshell (http://oreil.ly/XML_Nutshell) by Elliotte Rusty Harold and W. Scott Means (O’Reilly).

Generating XML

Just as PHP can be used to generate dynamic HTML, it can also be used to generate dynamic XML. You can generate XML for other programs to make use of based on forms, database queries, or anything else you can do in PHP. One application for dynamic XML is Rich Site Summary (RSS), a file format for syndicating news sites. You can read an article’s information from a database or from HTML files and emit an XML summary file based on that information.

Generating an XML document from a PHP script is simple. Simply change the MIME type of the document, using the header() function, to "text/xml". To emit the <?xml ... ?> declaration without it being interpreted as a malformed PHP tag, simply echo the line from within PHP code:

echo '<?xml version="1.0" encoding="ISO-8859-1" ?>';

Example 12-1 generates an RSS document using PHP. An RSS file is an XML document containing several channel elements, each of which contains some news item elements. Each news item can have a title, a description, and a link to the article itself. More properties of an item are supported by RSS than Example 12-1 creates. Just as there are no special functions for generating HTML from PHP, there are no special functions for generating XML. You just echo it!

<?php
header('Content-Type: text/xml');
echo "<?xml version="1.0" encoding="ISO-8859-1" ?>";
?>
<!DOCTYPE rss PUBLIC "-//Netscape Communications//DTD RSS 0.91//EN"
 "http://my.netscape.com/publish/formats/rss-0.91.dtd">

<rss version="0.91">
 <channel>
 <?php
 // news items to produce RSS for
 $items = array(
 array(
 'title' => "Man Bites Dog",
 'link' => "http://www.example.com/dog.php",
 'desc' => "Ironic turnaround!"
 ),
 array(
 'title' => "Medical Breakthrough!",
 'link' => "http://www.example.com/doc.php",
 'desc' => "Doctors announced a cure for me."
 )
 );

 foreach($items as $item) {
 echo "<item>
";
 echo " <title>{$item['title']}</title>
";
 echo " <link>{$item['link']}</link>
";
 echo " <description>{$item['desc']}</description>
";
 echo " <language>en-us</language>
";
 echo "</item>

";
 } ?>
 </channel>
</rss>

This script generates output such as the following:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE rss PUBLIC "-//Netscape Communications//DTD RSS 0.91//EN"
 "http://my.netscape.com/publish/formats/rss-0.91.dtd">
<rss version="0.91">
 <channel>
<item>
 <title>Man Bites Dog</title>
 <link>http://www.example.com/dog.php</link>
 <description>Ironic turnaround!</description>
 <language>en-us</language>
</item>

<item>
 <title>Medical Breakthrough!</title>
 <link>http://www.example.com/doc.php</link>
 <description>Doctors announced a cure for me.</description>
 <language>en-us</language>
</item>
 </channel>
</rss>

Parsing XML

Say you have a set of XML files, each containing information about a book, and you want to build an index showing the document title and its author for the collection. You need to parse the XML files to recognize the title and author elements and their contents. You could do this by hand with regular expressions and string functions such as strtok(), but it’s a lot more complex than it seems. In addition, such methods are prone to breakage even with valid XML documents. The easiest and quickest solution is to use one of the XML parsers that ship with PHP.

PHP includes three XML parsers: one event-driven library based on the expat C library, one DOM-based library, and one for parsing simple XML documents named, appropriately, SimpleXML.

The most commonly used parser is the event-based library, which lets you parse but not validate XML documents. This means you can find out which XML tags are present and what they surround, but you can’t find out if they’re the right XML tags in the right structure for this type of document. In practice, this isn’t generally a big problem.

PHP’s event-based XML parser calls various handler functions you provide while it reads the document as it encounters certain “events,” such as the beginning or end of an element.

In the following sections, we discuss the handlers you can provide, the functions to set the handlers, and the events that trigger the calls to those handlers. We also provide sample functions for creating a parser to generate a map of the XML document in memory, tied together in a sample application that pretty-prints XML.

xml_set_element_handler(parser, start_element, end_element);

startElementHandler(parser, element, &attributes);

function startElement($parser, $name, $attributes) {
 $outputAttributes = array();

 if (count($attributes)) {
 foreach($attributes as $key => $value) {
 $outputAttributes[] = "<font color="gray">{$key}="{$value}"</font>";
 }
 }

 echo "&lt;<b>{$name}</b> " . join(' ', $outputAttributes) . '&gt;';
}

endElementHandler(parser, element);

function endElement($parser, $name) {
 echo "&lt;<b>/{$name}</b>&gt;";
}

xml_set_character_data_handler(parser, handler);

characterDataHandler(parser, cdata);

function characterData($parser, $data) {
 echo $data;
}

xml_set_processing_instruction_handler(parser, handler);

<? target instructions ?>

processingInstructionHandler(parser, target, instructions);

function processing_instruction($parser, $target, $code) {
 if ($target === 'php') {
 eval($code);
 }
}

xml_set_external_entity_ref_handler(parser, handler);

externalEntityHandler(parser, entity, base, system, public);

function externalEntityReference($parser, $names, $base, $systemID, $publicID) {
 if ($systemID) {
 if (!list ($parser, $fp) = createParser($systemID)) {
 echo "Error opening external entity {$systemID}
";

 return false;
 }

 return parse($parser, $fp);
 }

 return false;
}

<!DOCTYPE doc [
 <!NOTATION jpeg SYSTEM "image/jpeg">
 <!ENTITY logo SYSTEM "php-tiny.jpg" NDATA jpeg>
]>

xml_set_notation_decl_handler(parser, handler);

notationHandler(parser, notation, base, system, public);

xml_set_unparsed_entity_decl_handler(parser, handler);

unparsedEntityHandler(parser, entity, base, system, public, notation);

xml_set_default_handler(parser, handler);

defaultHandler(parser, text);

function default($parser, $data) {
 echo "<font color="red">XML: Default handler called with '{$data}'</font>
";
}

xml_parser_set_option(parser, option, value);

$value = xml_parser_get_option(parser, option);

xml_parser_set_option(XML_OPTION_CASE_FOLDING, false);

xml_parser_set_option(XML_OPTION_SKIP_WHITE, true);

xml_parser_set_option(XML_OPTION_SKIP_TAGSTART, 4);
// <xsl:name> truncates to "name"

$parser = xml_parser_create([encoding]);

$success = xml_parse(parser, data[, final ]);

function createParser($filename) {
 $fh = fopen($filename, 'r');
 $parser = xml_parser_create();
 
 xml_set_element_handler($parser, "startElement", "endElement");
 xml_set_character_data_handler($parser, "characterData");
 xml_set_processing_instruction_handler($parser, "processingInstruction");
 xml_set_default_handler($parser, "default");
 
 return array($parser, $fh);
}
 
function parse($parser, $fh) {
 $blockSize = 4 * 1024; // read in 4 KB chunks
 
 while ($data = fread($fh, $blockSize)) {
 if (!xml_parse($parser, $data, feof($fh))) {
 // an error occurred; tell the user where
 echo 'Parse error: ' . xml_error_string($parser) . " at line " .
 xml_get_current_line_number($parser);
 
 return false;
 }
 }
 
 return true;
}
 
if (list ($parser, $fh) = createParser("test.xml")) {
 parse($parser, $fh);
 fclose($fh);
 
 xml_parser_free($parser);
}

$error = xml_get_error_code($parser);

XML_ERROR_NONE
XML_ERROR_NO_MEMORY
XML_ERROR_SYNTAX
XML_ERROR_NO_ELEMENTS
XML_ERROR_INVALID_TOKEN
XML_ERROR_UNCLOSED_TOKEN
XML_ERROR_PARTIAL_CHAR
XML_ERROR_TAG_MISMATCH
XML_ERROR_DUPLICATE_ATTRIBUTE
XML_ERROR_JUNK_AFTER_DOC_ELEMENT
XML_ERROR_PARAM_ENTITY_REF
XML_ERROR_UNDEFINED_ENTITY
XML_ERROR_RECURSIVE_ENTITY_REF
XML_ERROR_ASYNC_ENTITY
XML_ERROR_BAD_CHAR_REF
XML_ERROR_BINARY_ENTITY_REF
XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF
XML_ERROR_MISPLACED_XML_PI
XML_ERROR_UNKNOWN_ENCODING
XML_ERROR_INCORRECT_ENCODING
XML_ERROR_UNCLOSED_CDATA_SECTION
XML_ERROR_EXTERNAL_ENTITY_HANDLING

$message = xml_error_string(code);

$error = xml_get_error_code($parser);

if ($error != XML_ERROR_NONE) {
 die(xml_error_string($error));
}

xml_set_object(object);

Sample Parsing Application

Let’s develop a program to parse an XML file and display different types of information from it. The XML file given in Example 12-8 contains information on a set of books.

Example 12-8. books.xml file

<?xml version="1.0" ?>
<library>
 <book>
 <title>Programming PHP</title>
 <authors>
 <author>Rasmus Lerdorf</author>
 <author>Kevin Tatroe</author>
 <author>Peter MacIntyre</author>
 </authors>
 <isbn>1-56592-610-2</isbn>
 <comment>A great book!</comment>
 </book>
 <book>
 <title>PHP Pocket Reference</title>
 <authors>
 <author>Rasmus Lerdorf</author>
 </authors>
 <isbn>1-56592-769-9</isbn>
 <comment>It really does fit in your pocket</comment>
 </book>
 <book>
 <title>Perl Cookbook</title>
 <authors>
 <author>Tom Christiansen</author>
 <author whereabouts="fishing">Nathan Torkington</author>
 </authors>
 <isbn>1-56592-243-3</isbn>
 <comment>Hundreds of useful techniques, most
 applicable to PHP as well as Perl</comment>
 </book>
</library>

The PHP application parses the file and presents the user with a list of books, showing just the titles and authors. This menu is shown in Figure 12-1. The titles are links to a page showing the complete information for a book. A page of detailed information for Programming PHP is shown in Figure 12-2.

We define a class, BookList, whose constructor parses the XML file and builds a list of records. There are two methods on a BookList that generate output from that list of records. The showMenu() method generates the book menu, and the showBook() method displays detailed information on a particular book.

Parsing the file involves keeping track of the record, which element we’re in, and which elements correspond to records (book) and fields (title, author, isbn, and comment). The $record property holds the current record as it’s being built, and $currentField holds the name of the field we’re currently processing (e.g., title). The $records property is an array of all the records we’ve read so far.

Figure 12-1. Book menu

Figure 12-2. Book details

Two associative arrays, $fieldType and $endsRecord, tell us which elements correspond to fields in a record and which closing element signals the end of a record. Values in $fieldType are either 1 or 2, corresponding to a simple scalar field (e.g., title) or an array of values (e.g., author), respectively. We initialize those arrays in the constructor.

The handlers themselves are fairly straightforward. When we see the start of an element, we work out whether it corresponds to a field we’re interested in. If it is, we set the $currentField property to be that field name so when we see the character data (e.g., the title of the book), we know which field it’s the value for. When we get character data, we add it to the appropriate field of the current record if $currentField says we’re in a field. When we see the end of an element, we check to see if it’s the end of a record; if so, we add the current record to the array of completed records.

One PHP script, given in Example 12-9, handles both the book menu and book details pages. The entries in the book menu link back to the menu URL with a GET parameter identifying the ISBN of the book to display.

Example 12-9. bookparse.php

<html>
 <head>
 <title>My Library</title>
 </head>

 <body>
 <?php
 class BookList {
 const FIELD_TYPE_SINGLE = 1;
 const FIELD_TYPE_ARRAY = 2;
 const FIELD_TYPE_CONTAINER = 3;

 var $parser;
 var $record;
 var $currentField = '';
 var $fieldType;
 var $endsRecord;
 var $records;

 function __construct($filename) {
 $this->parser = xml_parser_create();
 xml_set_object($this->parser, $this);
 xml_set_element_handler($this->parser, "elementStarted", "elementEnded");
 xml_set_character_data_handler($this->parser, "handleCdata");

 $this->fieldType = array(
 'title' => self::FIELD_TYPE_SINGLE,
 'author' => self::FIELD_TYPE_ARRAY,
 'isbn' => self::FIELD_TYPE_SINGLE,
 'comment' => self::FIELD_TYPE_SINGLE,
 );

 $this->endsRecord = array('book' => true);

 $xml = join('', file($filename));
 xml_parse($this->parser, $xml);

 xml_parser_free($this->parser);
 }

 function elementStarted($parser, $element, &$attributes) {
 $element = strtolower($element);

 if ($this->fieldType[$element] != 0) {
 $this->currentField = $element;
 }
 else {
 $this->currentField = '';
 }
 }

 function elementEnded($parser, $element) {
 $element = strtolower($element);

 if ($this->endsRecord[$element]) {
 $this->records[] = $this->record;
 $this->record = array();
 }

 $this->currentField = '';
 }

 function handleCdata($parser, $text) {
 if ($this->fieldType[$this->currentField] == self::FIELD_TYPE_SINGLE) {
 $this->record[$this->currentField] .= $text;
 }
 else if ($this->fieldType[$this->currentField] == self::FIELD_TYPE_ARRAY) {
 $this->record[$this->currentField][] = $text;
 }
 }

 function showMenu() {
 echo "<table>
";

 foreach ($this->records as $book) {
 echo "<tr>";
 echo "<th><a href="{$_SERVER['PHP_SELF']}?isbn={$book['isbn']}">";
 echo "{$book['title']}</a></th>";
 echo "<td>" . join(', ', $book['author']) . "</td>
";
 echo "</tr>
";
 }

 echo "</table>
";
 }

 function showBook($isbn) {
 foreach ($this->records as $book) {
 if ($book['isbn'] !== $isbn) {
 continue;
 }

 echo "<p><b>{$book['title']}</b> by " . join(', ', $book['author']) . "<br />";
 echo "ISBN: {$book['isbn']}<br />";
 echo "Comment: {$book['comment']}</p>
";
 }

 echo "<p>Back to the <a href="{$_SERVER['PHP_SELF']}">list of books</a>.</p>";
 }
 }

 $library = new BookList("books.xml");

 if (isset($_GET['isbn'])) {
 // return info on one book
 $library->showBook($_GET['isbn']);
 }
 else {
 // show menu of books
 $library->showMenu();
 } ?>
 </body>
</html>

Parsing XML with the DOM

The DOM parser provided in PHP is much simpler to use, but what you take out in complexity comes back in memory usage—in spades. Instead of firing events and allowing you to handle the document as it is being parsed, the DOM parser takes an XML document and returns an entire tree of nodes and elements:

$parser = new DOMDocument();
$parser->load("books.xml");
processNodes($parser->documentElement);

function processNodes($node) {
 foreach ($node->childNodes as $child) {
 if ($child->nodeType == XML_TEXT_NODE) {
 echo $child->nodeValue;
 }
 else if ($child->nodeType == XML_ELEMENT_NODE) {
 processNodes($child);
 }
 }
}

Parsing XML with SimpleXML

If you’re consuming very simple XML documents, you might consider the third library provided by PHP, SimpleXML. SimpleXML doesn’t have the ability to generate documents as the DOM extension does, and isn’t as flexible or memory-efficient as the event-driven extension, but it makes it very easy to read, parse, and traverse simple XML documents.

SimpleXML takes a file, string, or DOM document (produced using the DOM extension) and generates an object. Properties on that object are arrays providing access to elements in each node. With those arrays, you can access elements using numeric indices and attributes using non-numeric indices. Finally, you can use string conversion on any value you retrieve to get the text value of the item.

For example, we could display all the titles of the books in our books.xml document using:

$document = simplexml_load_file("books.xml");

foreach ($document->book as $book) {
 echo $book->title . "
";
}

Using the children() method on the object, you can iterate over the child nodes of a given node; likewise, you can use the attributes() method on the object to iterate over the attributes of the node:

$document = simplexml_load_file("books.xml");

foreach ($document->book as $node) {
 foreach ($node->attributes() as $attribute) {
 echo "{$attribute}
";
 }
}

Finally, using the asXml() method on the object, you can retrieve the XML of the document in XML format. This lets you change values in your document and write it back out to disk easily:

$document = simplexml_load_file("books.xml");

foreach ($document->children() as $book) {
 $book->title = "New Title";
}

file_put_contents("books.xml", $document->asXml());

Transforming XML with XSLT

Extensible Stylesheet Language Transformations (XSLT) is a language for transforming XML documents into different XML, HTML, or any other format. For example, many websites offer several formats of their content—HTML, printable HTML, and WML (Wireless Markup Language) are common. The easiest way to present these multiple views of the same information is to maintain one form of the content in XML and use XSLT to produce the HTML, printable HTML, and WML.

PHP’s XSLT extension uses the Libxslt C library to provide XSLT support.

Three documents are involved in an XSLT transformation: the original XML document, the XSLT document containing transformation rules, and the resulting document. The final document doesn’t have to be in XML; in fact, it’s common to use XSLT to generate HTML from XML. To do an XSLT transformation in PHP, you create an XSLT processor, give it some input to transform, and then destroy the processor.

Create a processor by creating a new XsltProcessor object:

$processor = new XsltProcessor;

Parse the XML and XSL files into DOM objects:

$xml = new DomDocument;
$xml->load($filename);

$xsl = new DomDocument;
$xsl->load($filename);

Attach the XML rules to the object:

$processor->importStyleSheet($xsl);

Process a file with the transformToDoc(), transformToUri(), or transformToXml() methods:

$result = $processor->transformToXml($xml);

Each takes the DOM object representing the XML document as a parameter.

Example 12-10 is the XML document we’re going to transform. It is in a similar format to many of the news documents you find on the web.

<?xml version="1.0" ?>

<news xmlns:news="http://slashdot.org/backslash.dtd">
 <story>
 <title>O'Reilly Publishes Programming PHP</title>
 <url>http://example.org/article.php?id=20020430/458566</url>
 <time>2002-04-30 09:04:23</time>
 <author>Rasmus and some others</author>
 </story>

 <story>
 <title>Transforming XML with PHP Simplified</title>
 <url>http://example.org/article.php?id=20020430/458566</url>
 <time>2002-04-30 09:04:23</time>
 <author>k.tatroe</author>
 <teaser>Check it out</teaser>
 </story>
</news>

Example 12-11 is the XSL document we’ll use to transform the XML document into HTML. Each xsl:template element contains a rule for dealing with part of the input document.

<?xml version="1.0" encoding="utf-8" ?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="html" indent="yes" encoding="utf-8" />

<xsl:template match="/news">
 <html>
 <head>
 <title>Current Stories</title>
 </head>
 <body bgcolor="white" >
 <xsl:call-template name="stories"/>
 </body>
 </html>
</xsl:template>

<xsl:template name="stories">
 <xsl:for-each select="story">
 <h1><xsl:value-of select="title" /></h1>

 <p>
 <xsl:value-of select="author"/> (<xsl:value-of select="time"/>)<br />
 <xsl:value-of select="teaser"/>
 [ <a href="{url}">More</a> ]
 </p>

 <hr />
 </xsl:for-each>
</xsl:template>

</xsl:stylesheet>

Example 12-12 is the very small amount of code necessary to transform the XML document into an HTML document using the XSL stylesheet. We create a processor, run the files through it, and print the result.

<?php
$processor = new XsltProcessor;

$xsl = new DOMDocument;
$xsl->load("rules.xsl");
$processor->importStyleSheet($xsl);

$xml = new DomDocument;
$xml->load("feed.xml");
$result = $processor->transformToXml($xml);

echo "<pre>{$result}</pre>";

Although it doesn’t specifically discuss PHP, Doug Tidwell’s book XSLT (http://oreil.ly/XSLT_2E) provides a detailed guide to the syntax of XSLT stylesheets.

What’s Next

While XML remains a major format for sharing data, a simplified version of JavaScript data encapsulation, known as JSON, has rapidly become the de facto standard for simple, readable, and terse sharing of web service responses and other data. That’s the subject we’ll turn to in the next chapter.