Manual

Object-oriented abstraction for PHP's xml extension.

Introduction

Introduction – Introduction to XML_Parser

Introduction to XML_Parser

XML_Parser provides an object-oriented abstraction to PHP's ext/xml. It helps you processing XML documents by supplying methods that are needed when working with XML documents, like automatic error handling, parsing from a file, URL or string as well as an easy way to register callbacks.

XML_Parser uses SAX-based parsing, which is a simple API to retrieve information from XML documents. While the parser reads the document, it will call methods for the different nodes that are found. These nodes range from opening and closing tags to character data and processing instructions.

You will not be able to use XML_Parser directly to parse your documents, but you have to create a new class that extends XML_Parser and implement handlers for the tags and all other elements you need to process.

Several of PEAR's XML packages use this approach and thus rely on XML_Parser. If you would like to take a look at real-life examples, just install XML_RDDL, XML_Beautifier, XML_Statistics or XML_Serializer.

A tutorial that explains nearly every feature of XML_Parser is available at http://www.schst.net/articles/XML_Parser.

Example

Example – Example for the usage of XML_Parser

Basic example

This example shows you how to create a very simple parser that handles start, end elements (i.e. opening and closing tags), and character data (the "content" between the tags).

<?php
require_once 'XML/Parser.php';

class myParser extends XML_Parser
{
  function myParser()
  {
    parent::XML_Parser();
  }

 /**
  * handle start element
  *
  * @access private
  * @param  resource  xml parser resource
  * @param  string    name of the element
  * @param  array     attributes
  */
  function startHandler($xp, $name, $attribs)
  {
    printf('handle start tag: %s<br />', $name);
  }

 /**
  * handle end element
  *
  * @access private
  * @param  resource  xml parser resource
  * @param  string    name of the element
  */
  function endHandler($xp, $name)
  {
    printf('handle end tag: %s<br />', $name);
  }

 /**
  * handle character data
  *
  * @access private
  * @param  resource  xml parser resource
  * @param  string    character data
  */
  function cdataHandler($xp, $cdata)
  {
    // does nothing here, but might e.g. print $cdata
  }
}

$p = &new myParser();

$result = $p->setInputFile('xml_parser_file.xml');
$result = $p->parse();
?>

This parser will just output the names of the opening and closing tags that are found while parsing the document.

Modes

Modes – Explanation of possible parsing modes

Parser modes of XML_Parser

XML_Parser provides two modes for parsing:

func
event

In the 'event' mode, XML_Parser will always call the methods startHandler() and endHandler(), independent of the tag name. In these methods you'll have to check for the tagname, which is passed as the second parameter and decide what you need to do. In most cases, this is done with a switch/case statement.

In the 'func' mode, XML_Parser will call different methods based on the name of the tag. This allows you to dispatch different tags to different methods. The methods to handle the start tag have to be called xmltag_[tagname](), where [tagname] has to be substituted by the name of the element that you wish to process. That means if you wish to write a method to process all opening <title> tags, it has to be called xmltag_title.

Methods to handle closing tags have to be named xmltag_[tagname]_() (distinguishes from the start element handler using a traling underscore).

As XML tags may contain chars like ".", ":" and "-" and those chars are not allowed in PHP function names, XML_Parser will replace them with "_" when building the name of the callback function.

If a method does not exist, XML_Parser will skip the tag without handling the element, unless you implemented the methods xmltag() and xmltag_(), which will be used as fallback methods.

Setting the mode

There are two ways of setting the mode:

Specifying the mode in the constructor as the second parameter. In the subclass of XML_Parser that you implemented to process the XML documents, you will have to call XML_Parser::XML_Parser() in the constructor. This method accepts the mode as its second parameter.
Setting the mode using XML_Parser::setMode().

Choosing input

Choosing input – Explanation of different types of input data

Selecting the input for XML_Parser

XML_Parser is able to parse from several inputs:

filesystem or anything that can be accessed via stream
strings
resources

You will have to set the input using setInputFile(), setInputString() or setInput() and then call parse() to start the XML processing.

Parsing from a file

To parse from a file or URL, you'll have to set the name or URI using XML_Parser::setInputFile(). You may not only use files located on the filesystem, but any location that can be opened using fopen(). You may combine this functionality with the stream functions or PEAR's Streams packages to parse documents from shared memory, databases or anything else.

You may also use any of PHP's built-in wrappers to open HTTP or FTP locations as well as STDIN.

Parsing from a string

To parse an XML string, pass the string to XML_Parser (or your subclass of XML_Parser) using XML_Parser::setInputString(). A big advantage of SAX-based parsing is that the parser does not have to read the whole XML document to process it. If you are parsing very large documents, you should aboid setInputString() and use setInput() or setInputFile() instead.

Parsing from any resource

There's a third, but seldomly used way to specify XML_Parser's input. XML_Parser allows you to pass a PHP resource, like a file pointer that has been returned by fopen(). This can be useful, if you are generating the document on-the-fly and already opened it before. Instead of closing the file and passing its name to XML_Parser, you may simply use XML_Parser::setInput() to pass the resource. Make sure that the file pointer is at the correct location in your file using fseek().