The DOMIT! XML Parser Manual

An Element in XML is a type of content whose primary purpose is to contain other content. Elements are like bookends, and therefore consist of two parts: a start tag and an end tag.

Take a look at the first line of text in the cd library example: <cdlibrary>.

This is an example of a start tag. A start tag always:

At the bottom of the XML document is an end tag, which has a slightly different format: </cdlibrary>.

An end tag always:

An XML element can contain other types of XML content, including other elements. For example, the <person> element below contains a single <name> element:

<person>
  <name>John Heinstein</name>
</person>

It is possible to have an element containing no XML content. This is referred to as an empty element. There is a shorthand notation for representing an empty element:

<someEmptyElement/>

The longhand equivalent of this is:

<someEmptyElement></someEmptyElement>

Take a look at the first cd element in cdlibrary:

<cd discid="bb0c3c0c">
  <name>Robbie Fulks</name>
  <title>Couples in Trouble</title>
</cd>

Some additional information is present in the start tag: discid="bb0c3c0c". This is a type of XML content referred to as an Attribute. An attribute is used to store short, simple units of text.

An attribute always:

There can be multiple attributes in any start tag, as long as the attribute names are unique. For example:

<point x='10' y='35'/>

Textual XML content not stored in attributes is referred to as Character Data. Character data is always contained within elements, as we can see in the following example from the cdlibrary document

<name>Robbie Fulks</name>

<relationship>x &lt;= y + 1</relationship>

<htmlcode>&lt;img src="http://www.someurl.com/pic.jpg" /></htmlcode>

<htmlcode><![CDATA[<img src="http://www.someurl.com/pic.jpg"" />]]></htmlcode>

An XML Comment is a construct for adding remarks to your XML. It is similar to an HTML comment in that it:

A comment could be added to the cdlibrary example like this:

<?xml version="1.0"?>
<cdlibrary>
  <!-- Not many cds left after I got robbed -->
  <cd discid="bb0c3c0c">
    <name>Robbie Fulks</name>
    <title>Couples in Trouble</title>
  </cd>
  <cd discid="9b0ce70c">
    <name>Richard Thompson</name>
    <title>Mock Tudor</title>
  </cd>
  <cd discid="cf11720f">
    <name>Keller Williams</name>
    <title>Laugh</title>
  </cd>
</cdlibrary>

An XML Processing Instruction indicates to an application that it must perform some processing operation.

Every XML document is required to begin with a special type of processing instruction know as an XML Declaration (in practice, the XML declaration is often omitted):

<?xml version="1.0"?>

A processing instruction:

Another example of a processing instruction is found in the declaration of PHP code within an HTML page:

<?php  
//code here
?>

The target "php" informs a web server to process the subsequent data with a PHP interpreter rather than as HTML code.

A Document Type Declaration is a mechanism for defining what is an acceptable structure for an XML document. A validating XML parser can compare an XML document to its DTD and determine whether it is valid or not.

A DTD follows the XML declaration and comes before any actual XML data.

The following is an example of a DTD for an XML document containing a single element named "foo":

<!DOCTYPE foo [
  <!ELEMENT foo (#PCDATA)>
]>

A Document Node represents the DOM document itself -- the entire collection of nodes in a. It has:

An Element Node represents an XML Element. Take for instance the following <fullname> element:

<fullname>John Heinstein</fullname>

This element has:

An Attribute Node represents an XML Attribute. Take for instance the following serial attribute:

<item serial="123456"/>

This attribute has:

A Text Node represents XML Character Data that is not specified as a CDATA Section. Take for instance the text content bounded by the <fullname> element:

<fullname>John Heinstein</fullname>

This text node has:

A CDATA Section Node represents XML Character Data that is specified as a CDATA Section. Take the following CDATA Section:

<htmlcode><![CDATA[<img src="http://www.someurl.com/pic.jpg"" />]]></htmlcode>

This CDATA Section has:

A Comment Node represents an XML comment. Take the following XML comment:

<!-- Not many cds left after I got robbed -->

This comment node has:

A Processing Instruction Node represents an XML processing instruction. The most common processing instruction that you will find in a DOM Document is the XML Declaration:

<?xml version="1.0"?>

This processing instruction node has:

A Document Type Declaration represents an XML document type declaration.

DOMIT! is a non-validating parser and therefore does not check the validity of an XML document against the DTD. It simply stores a string representation of the DTD.

All nodes that are direct descendants of a node are referred to as its Child Nodes.

Only nodes of type element are permitted to contain a child nodes collection. Children themselves, however, can be of various node types, including element nodes, text and CDATA Section nodes, and comment nodes.

In the cdlibrary example:

A child node is referred to by its numerical index in the child nodes collection. The first child node is generally assigned an index of 1, although for technical reasons some DOM implementations will start at 0.

If an element contains no children, it will still have an child nodes collection (that is empty).

Note: Attribute nodes are not included in the child nodes collection. These are in a separate collection reserved specifically for attributes.

<cd discid="cf11720f">
  <name>Keller Williams</name>
  <title>Laugh</title>
</cd>

<cd discid="cf11720f">
  <name>Keller Williams</name>
  <title>Laugh</title>
</cd>

In the same way that one can travel down the hierarchy of a DOM document via the child nodes collection, the DOM specifies a way to travel up the hierarchy. The ancestor of any node is referred to as its Parent Node.

In our cdlibrary example:

Note: Attributes do not contain a reference to parent nodes.

The DOM specifies an explicit relationship between nodes that occupy the same level of a DOM tree. These nodes are referred to as Sibling Nodes.

One might think of the relationship between sibling nodes as the links in a chain. Each node knows about the node immediately preceding it and the node immediately following it.

Each element node contains an Attributes list, or a reference to the collection of attributes assigned to it. In the following example, the <item> element contains a list of five attributes:

<item desc="post" material="steel" length="120" diameter="5" price="0.75"/> 

These attributes can be accessed either by name or numerical index.

Each node in a DOM Document -- with the exclusion of attribute nodes -- contains a reference to the DOM Document that contains it. This is referred to as the Owner Document property of a node.

The root element of a DOM Document is always referred to as the Document Element.

In our cdlibrary example, the document element would be the <cdlibrary> node.

You create an instance of the DOMIT_Document class in the same way as any other PHP class:

$cdCollection =& new DOMIT_Document();

A DOMIT! Lite document is instantiated like this:

$cdCollection =& new DOMIT_Lite_Document();

Once a document has been instantiated, it is ready to be populated with XML data.

Note: to ensure PHP 4 backwards compatability, it is necessary to include an ampersand (&) symbol after the equal sign when returning a reference to a DOMIT_Document or any other DOMIT! object.

If we wanted to create a DOMIT_Document out of a PHP string, we would use the parseXML method. Take for instance, the cd collection XML described in the previous section:

$cdCollection =& new DOMIT_Document(); //instantiate document

//create string variable with XML text
$cdCollectionString = "<?xml version="1.0"?><cdlibrary><cd discid=\"bb0c3c0c\">
  <name>Robbie Fulks</name>
  <title>Couples in Trouble</title></cd>
  <cd discid=\"9b0ce70c\"><name>Richard Thompson</name>
  <title>Mock Tudor</title></cd><cd discid=\"cf11720f\">
  <name>Keller Williams</name>
  <title>Laugh</title></cd>
  </cdlibrary>";

//use parseXML method to populate document
$success = $cdCollection->parseXML($cdCollectionString, true); //parse document

parseXML returns true if the parsing is successful

The loadXML method of DOMIT_Document is used to load an XML string from a file or url. It uses an identical syntax to the parseXML method:

$cdCollection =& new DOMIT_Document();
$success = $cdCollection->loadXML("/xml/cdcollection.xml");

The above example parses a file from the file system.

To parse an url, you would specify the full HTTP address as the first parameter:

$cdCollection =& new DOMIT_Document();
$success = $cdCollection->loadXML("http://www.engageinteractive.com/rssfeed.xml");

DOMIT! relies on an underlying SAX parser to parse XML data. You have the choice of one of two SAX parsers:

The second parameter of both parseXML and loadXML allows you to specify a SAX parser. The useSAXY parameter is a boolean whose default value is true. Specifying false will check whether Expat is available and use it to parse and pass the XML data to DOMIT!:

$cdCollection =& new DOMIT_Document();
$success = $cdCollection->loadXML("/xml/cdcollection.xml", false); //Expat specified

If Expat cannot be detected, DOMIT! will revert to SAXY for its parsing.

To determine whether Expat or SAXY was used to generate a DOMIT_Document, you can use the parsedBy method:

$saxParser = $xmldoc->parsedBy();

The parsedBy method returns a string with a value of either EXPAT or SAXY.

As of version 1.0, DOMIT! comes bundled with the php_http_client library, written by Engage Interactive. With the useHTTPClient method, DOMIT! can be forced to establish a standard HTTP connection to the web server hosting the XML file:

$cdCollection =& new DOMIT_Document();

//specify that an HTTP client should be used to retrieve XML
$xmldoc->useHTTPClient(true); 

//call loadXML method as usual
$success = $cdCollection->loadXML("http://www.engageinteractive.com/rssfeed.xml", false); 

The HTTP connection will be attempted on port 80.

If you need to establish an HTTP connection to retrieve your XML data, but the useHTTPClient method does not provide enough flexibility, the setConnection method of DOMIT_Document can be used to manually set the parameters of the connection.

$cdCollection =& new DOMIT_Document();
$xmldoc->setConnection('http://www.engageinteractive.com', '/', '955');

//call loadXML method as usual
$success = $cdCollection->loadXML("http://www.engageinteractive.com/rssfeed.xml", false);

In the above example, an HTTP connection will be established on port 955 of host http://www.engageinteractive.com. You can also use a raw IP address for the host, such as http://198.162.0.10

Note that you can also pass in a user name and password to the setConnection method, if you must use HTTP Authorization to establish your connection. For more about HTTP Authorization, please see the entry on the setAuthorization method.

The HTTP specification allows for a basic (i.e., not particularly secure) type of authorization called HTTP Authorization. If the XML file that you require is protected by this sort of authentication, you can use the setAuthorization method of DOMIT!.

setAuthorization is used in conjunction with the setConnection method, and requires that you provide a plain text username and password:

$cdCollection =& new DOMIT_Document();
$xmldoc->setConnection('http://www.engageinteractive.com', '/', '955');
$xmldoc->setAuthorization('johnheinstein', 'mypassword');

//call loadXML method as usual
$success = $cdCollection->loadXML("http://www.engageinteractive.com/rssfeed.xml", false);

An HTTP proxy is a server that acts as an intermediary between an HTTP client (a user's browser) and the Internet. It is used to enforce security, administrative control, and caching services. If you are behind a firewall, for instance, and must connect to a proxy server to access web based resources, then the setProxyConnection method will allow you to access such data.

The setProxyConnection method works inn exactly the same way as setConnection:

$cdCollection =& new DOMIT_Document();
$xmldoc->setProxyConnection('http://www.myproxyconnection.com', '/', '1060');

//call loadXML method as usual
$success = $cdCollection->loadXML("http://www.engageinteractive.com/rssfeed.xml", false);

The setProxyAuthorization is called in exactly the same way as setAuthorization. Just provide a valid user name and password:

$cdCollection =& new DOMIT_Document();
$xmldoc->setProxyConnection('http://www.myproxyconnection.com', '/', '1060');
$xmldoc->setProxyAuthorization('johnheinstein', 'mypassword');

//call loadXML method as usual
$success = $cdCollection->loadXML("http://www.engageinteractive.com/rssfeed.xml", false);

By default, when loading an XML document, DOMIT! removes what it considers insignificant whitespace -- such as the tabs between XML tags that are used for formatting purposes only.

Whitespace can be retained, however, if the following is called prior to loading or parsing:

$cdCollection->preserveWhitespace(true);

When DOMIT! parses or loads an XML Document, often entities are present which must be transformed into their corresponding character representations. Generally it is the responsibility of the DOCTYPE declaration to delineate these conversions.

However, DOMIT! is a non-validating parser, and is unaware of constraints placed on a document by the DOCTYPE.

The appendEntityTranslationTable method is an alternate way of specifying character equivalents of entities.

It takes a single parameter -- an associative array of entities mapped to their equivalent characters. For example, if one wanted to instruct DOMIT! to convert all © entities into © :

//create translation table
$myTranslationTable = array('©' => '©');

//pass table to document
$cdCollection->appendEntityTranslationTable($myTranslationTable);

If the resolveErrors method is called, DOMIT! will attempt to locate and fix any problems with improperly formatted XML code. The method must be called before parsing begins; just pass it a value of true:

$cdCollection =& new DOMIT_Document();
$cdCollection->resolveErrors(true);
$success = $cdCollection->loadXML("/xml/cdcollection.xml");

Note that resolveErrors may have an impact on speed, and should be used judiciously.

Currently, resolveErrors only searches for and replaces ampersands that have not been encoded as &

If loadXML or parseXML return false, an error has occurred in processing. The methods getErrorCode and getErrorString can be used to diagnose where the problem lies.

getErrorCode returns a numerical description of the error, and getErrorString returns a textual description of the error. For example:

$cdCollection =& new DOMIT_Document();
$cdCollection->resolveErrors(true);
$success = $cdCollection->loadXML("/xml/cdcollection.xml");

if ($success) {
  //process XML
}
else {
  //an error has occurred; echo to browser
  echo "Error code: " . $cdCollection->getErrorCode();
  echo "\n<br />";
  echo "Error string: " . $cdCollection->getErrorString();
}

If you would like to set a custom error handler for DOMIT! to handle runtime XML processing errors, you can use a static method of the DOMIT_DOMException class: setErrorHandler.

It takes a single parameter -- the method to handle the error.

The custom errorhandler method must have the following method signature...

function myCustomErrorHandler($errorNum, $errorString)

...where $errorNum is an integer signifying the number of the error, and $errorString is a string giving a description of the error.

For example, if you wrote a function to handle your DOMIT! errors that looked like this:

function myErrorHandler($errorNum, $errorString) {
  echo "The error number is " . $errorNum . " and " the error string is " . $errorString;
}

You could invoke it like this:

DOMIT_DOMException::setErrorHandler("myErrorHandler");

If the myErrorHandler function was a method of a class named ErrorHandlers rather than a standalone function, you could invoke setErrorHandler like this:

DOMIT_DOMException::setErrorHandler(array("ErrorHandlers", "myErrorHandler"));

The DOMIT_DOMException::setErrorMode method allows you to define the behavior of DOMIT! when an exception occurs. It takes a single parameter -- an integer or interger constant representing the error mode:

For example:

$cdCollection =& new DOMIT_Document();

//sets DOMIT! to die on an exception
DOMIT_DOMException::setErrorMode(DOMIT_ONERROR_DIE);

The DOMIT_DOMException::setErrorLog method allows you to specify a file to which error messages are logged and timestamped. This is a useful feature for debugging XML parsing problems.

It takes two parameters:

The following example specifies that errors are to be logged to the file 'errorLog.txt':

$cdCollection =& new DOMIT_Document();

//specifies that error logging is to be enabled and the error log filename
DOMIT_DOMException::setErrorLog(true, 'errorLog.txt');

Take the document element node of the cd library example above. Once a reference to the <cdlibrary> node has been obtained using the documentElement keyword, we can see what it contains:

$myDocumentElement =& $cdCollection->documentElement;
echo $myDocumentElement->toString(true);

The following string will be echoed to the browser window:

<cdlibrary><cd discid="bb0c3c0c"><name>Robbie Fulks</name><title>Couples in Trouble</title></cd><cd discid="9b0ce70c"><name>Richard Thompson</name><title>Mock Tudor</title></cd><cd discid="cf11720f"><name>Keller Williams</name><title>Laugh</title></cd></cdlibrary>

The first parameter of toString , if set to true, converts special HTML characters into their encoded version (i.e. & into &) so that they will display properly in a browser.

If you would like unconverted raw text to be output (for instance, when echoing to a command line interface) substitute a value of false:

echo $myDocumentElement->toString(false);

One drawback of the toString output is that it is not particularly readable, since all text of the node is compressed into one line. The toNormalizedString method will output text that is much more nicely formatted:

$myDocumentElement =& $cdCollection->documentElement;
echo $myDocumentElement->toNormalizedString(true);

The following string will be echoed to the browser window:

<cdlibrary>
  <cd discid="bb0c3c0c">
    <name>Robbie Fulks</name>
    <title>Couples in Trouble</title>
  </cd>
  <cd discid="9b0ce70c">
    <name>Richard Thompson</name>
    <title>Mock Tudor</title>
  </cd>
  <cd discid="cf11720f">
    <name>Keller Williams</name>
    <title>Laugh</title>
  </cd>
</cdlibrary>

As with the toString method, passing a value of false into toNormalizedString outputs text that is not formatted for HTML display.

When outputting XML using toString or toNormalized string, by default DOMIT! represents empty elements using the abbreviated convention:

<anEmptyElement />

If you prefer the tags to be expanded instead, use the expandEmptyElementTags method:

$xmldoc->expandEmptyElementTags(true);

When using DOMIT! to render XHTML documents, often it is necessary to leave some tags unexpanded, such as the <br /> tag. The expandEmptyElementTags method allows you to pass in an array of exceptions to the expansion rule:

//create array of exceptions to the empty element expansion rule
$expansionExceptions = array('br', 'hr');

//invoke expansion rule, passing in array of exceptions as second parameter
$xmldoc->expandEmptyElementTags(true, $expansionExceptions);

This might result in output that looked like this:

<html>
  <body>
    <p>This is a test</p>
    <p></p>
    <br />
  </body>
</html>

As explained previously, each node in a DOM Document has a list of references to the nodes contained directly beneath it in the tree: its Child Nodes.

In DOMIT!, the child nodes exist as a standard PHP array named childNodes.

To grab a reference to the childNodes array of a node, use the following syntax:

//get a reference to the childNodes collection of the document element
$myChildNodes =& $cdCollection->documentElement->childNodes;

Note: When returning areference to the childNodes array in PHP4, always remember to use the reference (&) operator, or you will be returned a shallow copy.

It is good practice, prior to grabbing a reference to the childNodes array, to use the hasChildNodes method to check if any child nodes exist:

//ensure that there are childNodes before bothering to work with the childNodes array
if ($cdCollection->documentElement->hasChildNodes()) {
  $myChildNodes =& $cdCollection->documentElement->childNodes;
}

The number of child nodes is stored in the childCount property. You can use this value to traverse the childNodes array and access its individual nodes:

//ensure that there are childNodes before bothering to work with the childNodes array
if ($cdCollection->documentElement->hasChildNodes()) {

  //get a reference to the childNodes collection of the document element
  $myChildNodes =& $cdCollection->documentElement->childNodes;

  //get the total number of childNodes for the document element
  $numChildren =& $cdCollection->documentElement->childCount;

  //iterate through the collection
  for ($i = 0; $i < $numChildren; $i++) {

    //get a reference to the i childNode
    $currentNode =& myChildNodes[$i];
    
    //echo out the node to browser
    echo ("Node $i contents are: \n<br />" . 
      $currentNode->toNormalizedString(true) . "\n<br />\n<br />");
  }
}

The above example will return:

Node 1 contents are:
<cd discid="bb0c3c0c">
  <name>Robbie Fulks</name>
  <title>Couples in Trouble</title>
</cd>

Node 2 contents are:
<cd discid="9b0ce70c">
  <name>Richard Thompson</name>
  <title>Mock Tudor</title>
</cd>

Node 3 contents are:
<cd discid="cf11720f">
  <name>Keller Williams</name>
  <title>Laugh</title>
</cd>

The childNodes array is not the only means of accessing the children of a node.

The firstChild property of a node returns a reference to a node's first child node:

if ($cdCollection->documentElement->hasChildNodes()) {

  //get reference to first child node of document element
  $firstChildNode =& $cdCollection->documentElement->firstChild;

  //echo out the node to browser
  echo ("The contents of the first child node are: \n<br />" . 
      $firstChildNode->toNormalizedString(true));
  }
}

The above example will return:

The contents of the first child node are:
<cd discid="bb0c3c0c">
  <name>Robbie Fulks</name>
  <title>Couples in Trouble</title>
</cd>

Note: If there are no child nodes present, a value of null is returned.

The lastChild property of a node returns a reference to a node's last child node:

if ($cdCollection->documentElement->hasChildNodes()) {

  //get reference to last child node
  $lastChildNode =& $cdCollection->documentElement->lastChild;

  //echo out the node to browser
  echo ("The contents of the last child node are: \n<br />" . 
      $lastChildNode->toNormalizedString(true));
  }
}

The above example will return:

The contents of the last child node are:
<cd discid="cf11720f">
  <name>Keller Williams</name>
  <title>Laugh</title>
</cd>

If there are no child nodes present, a value of null is returned.

Nodes that occupy the same level of a DOM tree are called siblings. The DOM conceives of these nodes as being chained in a sequence, with each node aware of the node immediately preceding and immediately following it.

The nextSibling property of a node returns a reference to the node prior to it in the sibling chain.

In the cdlibrary example, the next sibling of the Robbie Fulks <cd> node is the Richard Thompson <cd> node. One would access it like this:

if ($cdCollection->documentElement->hasChildNodes()) {

  //get reference to first cd node (the Robbie Fulks cd)
  $firstChildNode =& $cdCollection->documentElement->firstChild;

  //get a reference to the next sibling (the Richard Thompson cd)
  $nextSiblingNode =& $firstChildNode->nextSibling;

  //echo out the node to browser
  echo ("The contents of the next sibling are: \n<br />" . 
      $nextSiblingNode->toNormalizedString(true));
  }
}

The above example will return:

The contents of the next sibling are:
<cd discid="9b0ce70c">
  <name>Richard Thompson</name>
  <title>Mock Tudor</title>
</cd>

If there are no next sibling nodes present, a value of null is returned.

The lastSibling property of a node returns a reference to the node after it in the sibling chain.

In the cdlibrary example, the previous sibling of the Keller Williams <cd> node is the Richard Thompson <cd> node. One would access it like this:

if ($cdCollection->documentElement->hasChildNodes()) {

  //get reference to last cd node (the Keller Williams cd)
  $lastChildNode =& $cdCollection->documentElement->lastChild;

  //get a reference to the previous sibling (the Richard Thompson cd)
  $previousSiblingNode =& $lastChildNode->previousSibling;

  //echo out the node to browser
  echo ("The contents of the previous sibling are: \n<br />" . 
      $previousSiblingNode->toNormalizedString(true));
  }
}

The above example will return:

The contents of the previous sibling are:
<cd discid="9b0ce70c">
  <name>Richard Thompson</name>
  <title>Mock Tudor</title>
</cd>

If there are no previous sibling nodes present, a value of null is returned.

As the name implies, the parentNode property of a node returns a reference to the node one level above it in the DOM tree.

In the cdlibrary example, the parent node of the Robbie Fulks <cd> node is the document element <cdlibrary> node. One would access it like this:

if ($cdCollection->documentElement->hasChildNodes()) {

  //get reference to first cd node (the Robbie Fulks cd)
  $firstChildNode =& $cdCollection->documentElement->firstChild;

  //get a reference to the parent (cdlibrary) node
  $myParentNode =& $firstChildNode->parentNode;

  //echo out the node to browser
  echo ("The contents of the parent node of the Robbie Fulks cd node are: \n<br />" . 
      $myParentNode->toNormalizedString(true));
  }
}

The above example will return:

The contents of the parent node of the Robbie Fulks cd node are:
<cdlibrary>
  <cd discid="bb0c3c0c">
    <name>Robbie Fulks</name>
    <title>Couples in Trouble</title>
  </cd>
  <cd discid="9b0ce70c">
    <name>Richard Thompson</name>
    <title>Mock Tudor</title>
  </cd>
  <cd discid="cf11720f">
    <name>Keller Williams</name>
    <title>Laugh</title>
  </cd>
</cdlibrary>

If there is no parent node present, a value of null is returned. Note that only the document element node will have no parent.

Each node in a DOM document -- with the the exception of attribute nodes -- is considered to be "owned" by that document.

Use the ownerDocument property of a node to obtain a reference to the DOMIT! document:

if ($cdCollection->documentElement->hasChildNodes()) {

  //get reference to first cd node (the Robbie Fulks cd)
  $firstChildNode =& $cdCollection->documentElement->firstChild;

  //get a reference to the DOMIT document
  $myOwnerDocument =& $firstChildNode->ownerDocument;
}

The easiest way of getting the data from a text node, CDATA Section nodes, or comment node is through its nodeValue property.

Note: A common error that many DOM newbies make is to confuse a text node with the element node that contains it. It is important to realize that a text node is always the child of the containing element.

$cdCollection =& new DOMIT_Document();
$success = $cdCollection->loadXML("/xml/cdcollection.xml");

if ($success) {
  //get a reference to the <name> element of the Robbie Fulks cd
  $nameElement =& $cdCollection->documentElement->childNodes[0]->firstChild;

  //get a reference to the text node
  //(this step has been broken into multiple steps to emphasize that
  //a text node must be distinguished from its containing element!)
  $nameTextNode =& $nameElement->firstChild;

  //echo out the data in the text node 
  echo $nameTextNode->nodeName;
}

The above example returns:

Robbie Fulks

If you prefer, you can condense the above steps into a single line:

$myText  = $cdCollection->documentElement->childNodes[0]->firstChild->firstChild->nodeName;

The getData method is a wrapper for the nodeValue keyword and functions in exactly the same way:

$cdCollection =& new DOMIT_Document();
$success = $cdCollection->loadXML("/xml/cdcollection.xml");

if ($success) {
  //get a reference to the <name> element of the Robbie Fulks cd
  $nameElement =& $cdCollection->documentElement->childNodes[0]->firstChild;

  //get a reference to the text node
  //(this step has been broken into multiple steps to emphasize that
  //a text node must be distinguished from its containing element!)
  $nameTextNode =& $nameElement->firstChild;

  //echo out the data in the text node 
  echo $nameTextNode->getData();
}

In most cases, the getText method functions identically to nodeValue and getData. You can simply substitute the word getText for the word getData in the previous example and the results will be the same.

However, getText can also be called on an element. In this case, the concatenated text of all children beneath the element is returned. For instance:

$cdCollection =& new DOMIT_Document();
$success = $cdCollection->loadXML("/xml/cdcollection.xml");

if ($success) {
  //get a reference to the Robbie Fulks <cd> element
  $cdElement =& $cdCollection->documentElement->childNodes[0];

  //get ALL text beneath the cd element ("name" text + "title" text)
  $childText = $cdElement->getText();

  //echo out the concatenated data 
  echo childText;
}

The above example returns:

Robbie FulksCouples in Trouble

The getLength method indicates how many characters exist in a character data node:

$numCharacters = $myTexNode->getLength();

The substringData method returns a specified subset of characters from a character data node.

It takes two parameters:

To extract the first name from the "Robbie Fulks" text node, for example, one would do this:

$firstName = $rfTextNode->substringData(0,6);

To determine whether an element contains a particular attribute, you can use the hasAttribute method. It takes a single string parameter -- the name of the attribute -- and returns either true or false:

if ($cdCollection->documentElement->hasChildNodes()) {

  //get reference to first cd node (the Robbie Fulks cd)
  $firstChildNode =& $cdCollection->documentElement->firstChild;

  //determine whether it has an attribute named "discid" 
  if ($firstChildNode->hasAttribute("discid")) {
    echo ("I DO have a discid attribute");
  }
  else {
    echo ("I DO NOT have a discid attribute");
  }
}

The hasAttributes method returns true if an element contains at least one attribute.

if ($someNode->hasAttributes()) {
    echo ("I have at least one attribute");
  }
  else {
    echo ("I have no attributes");
  }

To obtain the value of a named attribute, use the getAttribute method. As with the hasAttribute method, you pass in the attribute name:

if ($cdCollection->documentElement->hasChildNodes()) {

  //get reference to first cd node (the Robbie Fulks cd)
  $firstChildNode =& $cdCollection->documentElement->firstChild;

  //determine whether it has an attribute named "discid" 
  if ($firstChildNode->hasAttribute("discid")) {

    //obtain the value of the discid attribute
    $attrValue = $firstChildNode->getAttribute("discid);

    //echo the value out to the browser
    echo ("Attribute value: " . $attrValue);
  }
  else {
    echo ("I DO NOT have a discid attribute");
  }
}

The above example returns:

bb0c3c0c

Note: If the attribute does not exist, an empty string (i.e., "") is returned.

The getAttribute method returns the value of an attribute node. If you would like to obtain a reference to the node itself, use the getAttributeNode method.

To obtain the value of an attribute node, use either the getValue method:

if ($cdCollection->documentElement->hasChildNodes()) {

  //get reference to first cd node (the Robbie Fulks cd)
  $firstChildNode =& $cdCollection->documentElement->firstChild;

  //determine whether it has an attribute named "discid" 
  if ($firstChildNode->hasAttribute("discid")) {

    //obtain a reference to the discid attribute node (don't forget the ampersand!)
    $attrNode =& $firstChildNode->getAttributeNode("discid);

    //echo the value out to the browser
    echo ("The value of the discid attribute is: \n<br />" . 
      $attrNode->getValue());
  }
  else {
    echo ("I DO NOT have a discid attribute");
  }
}

The above example returns:

The value of the discid attribute is:
bb0c3c0c

An attribute list is defined by the DOM specification as a Named Node Map. This is a type of node collection that allows you to access its members either by name or by index.

Although the attribute specific methods are in most cases sufficient, there may be times when you do not know in advance the names of an elements attributes. Using the named node map methods, you can query ther list to find out this data.

if ($cdCollection->documentElement->hasChildNodes()) {

  //get reference to first cd node (the Robbie Fulks cd)
  $firstChildNode =& $cdCollection->documentElement->firstChild;

  //get a reference to the attributes list / named node map (don't forget the ampersand!)
  $attrList =& $firstChildNode->attributes;
}

if ($cdCollection->documentElement->hasChildNodes()) {

  //get reference to first cd node (the Robbie Fulks cd)
  $firstChildNode =& $cdCollection->documentElement->firstChild;

  //get a reference to the attributes list / named node map (don't forget the ampersand!)
  $attrList =& $firstChildNode->attributes;

  //determine the number of members in the attribute list
  $numAttributes = $attrList->getLength();

  //iterate through the list
  for ($i = 0; $i < $numAttributes; $i++) {
    //get a reference to the attribute node at index i (don't forget the ampersand!)   
    $currAttr =& $attrList->item(i);

    //echo out the name and value of the attribute
    echo "The attribute at index " . i . " is named: " . $currAttr->getName();
    echo "\n<br /> Its value is: " . $currAttr->getValue(); 
  }
}

The attribute at index 1 is named: discid
Its value is: bb0c3c0c

The XML declaration can be acquired with the getXMLDeclaration method:

$myXMLDecl =& $xmldoc->getXMLDeclaration();

A reference to a processing instruction node is returned.

The Document Type Declaration can be acquired with the getDocType method:

$myDTD =& $xmldoc->getDocType();

A reference to a processing instruction node is returned.

To create a new DOM element, use the createElement method.

The createElement method takes a single parameter -- the name of the element.

$newElement =& $xmldoc->createElement("cdlibrary");

Note: Don't forget to include the ampersand for backwards compatibility with PHP4!

To create a new DOM text node, use the createTextNode method.

The createTextNode method takes a single parameter -- the text of the node.

$myText = 'Here is some dummy text';

$newTextNode =& $xmldoc->createTextNode($myText);

To create a new DOM CDATA Section, use the createCDATASection method.

The createCDATASection method takes a single parameter -- the text of the CDATA Section.

$myText = 'Here are some illegal XML characters: & <';

$newCDATASection =& $xmldoc->createCDATASection($myText);

To create a new DOM attribute, use the createAttribute method.

The createAttribute method takes two parameters:

$newAttribute =& $xmldoc->createAttribute("discid", "bb0c3c0c");

To create a new DOM comment, use the createComment method.

The createComment method takes a single parameter -- the text of the comment.

$myCommentText = 'This is a comment';

$newCommentNode =& $xmldoc->createComment($myCommentText);

To create a new DOM processing instruction, use the createProcessingInstruction method.

The createProcessingInstruction method takes a two parameters -- the text of the target and the text of the data.

//create target and data
$myTarget = 'xml';
$myData = 'version="1.0"';

//create processing instruction
$newProcessingInstructionNode =& $xmldoc->createProcessingInstruction($myTarget, $myData);

The setAttribute method takes two parameters:

The following example adds a discid attribute to a <cd> element:

//create cd element
$newNode =& $xmldoc->createElement('cd');

//add a discid attribute
$newNode->setAttribute('discid', 'bb0c3c0c');

//echo to browser
echo $newNode->toNormalizedString(true);

The result is:

<cd discid="bb0c3c0c"></cd>

The setAttribute method also adds an attribute to an element. It takes a single parameter -- an attribute node:

//create cd element
$newNode =& $xmldoc->createElement('cd');

//create a discid attribute node
$newAttr =& $xmldoc->createAttribute('discid', 'bb0c3c0c');

//add the attribute node to the element
$newNode->setAttributeNode($newAttr);

//echo to browser
echo $newNode->toNormalizedString(true);

The result is:

<cd discid="bb0c3c0c"></cd>

An attribute can be removed with the removeAttribute method. It takes a single parameter -- the name of the attribute to be removed.

The following example removes the discid attribute from the Charlie Hunter <cd> element:

$rootElement->firstChild->removeAttribute('discid');

//echo to browser
echo $rootElement->toNormalizedString(true);

The result is:

<cdlibrary>
  <cd>
    <name>Charlie Hunter</name>
    <title>Songs From the Analog Playground</title>
  </cd>
  <cd discid="9b0ce70c">
    <name>Richard Thompson</name>
    <title>Mock Tudor</title>
  </cd>
  <cd discid="cf11720f">
    <name>Keller Williams</name>
    <title>Laugh</title>
  </cd>
</cdlibrary>

An attribute can also be removed with the removeAttributeNode method. It takes a single parameter -- a reference to the attribute to be removed.

The following example removes the discid attribute from the Charlie Hunter <cd> element:

//get reference to attribute to be removed
$attrToRemove =& $rootElement->firstChild->getAttributeNode('discid');

//remove attribute
$rootElement->firstChild->removeAttributeNode($attrToRemove);

//echo to browser
echo $rootElement->toNormalizedString(true);

The result is:

<cdlibrary>
  <cd>
    <name>Charlie Hunter</name>
    <title>Songs From the Analog Playground</title>
  </cd>
  <cd discid="9b0ce70c">
    <name>Richard Thompson</name>
    <title>Mock Tudor</title>
  </cd>
  <cd discid="cf11720f">
    <name>Keller Williams</name>
    <title>Laugh</title>
  </cd>
</cdlibrary>

The setText method allows you to modify the text of an existing text node, CDATA Section, or comment.

To change the title of the Keller Williams cd, for example, you would do this:

//get reference to title text node of Keller Williams cd 
$titleTextNode =& $rootElement->childNodes[2]->childNodes[1]->firstChild;

//modify title
$titleTextNode->setText('Loop');

//echo to browser
echo $xmldoc->toNormalizedString(true);

The result is:

<?xml version="1.0"?>
<cdlibrary>
  <cd discid="a30e4c0d">
    <name>Charlie Hunter</name>
    <title>Songs From the Analog Playground</title>
  </cd>
  <cd discid="9b0ce70c">
    <name>Richard Thompson</name>
    <title>Mock Tudor</title>
  </cd>
  <cd discid="cf11720f">
    <name>Keller Williams</name>
    <title>Loop</title>
  </cd>
</cdlibrary>

//create a new element
$someElement =& $xmldoc->createElement('someElement');

//call setText on the element 
//(note that no child text node exists at this point, but one will be created)
$someElement->setText('Some sample text');

//echo to browser
echo $someElement->toNormalizedString(true);

<someElement>Some sample text</someElement>

The splitText method is accessible only from a text node. It allows you to split a text node into two text nodes, at a specified offset point. Both text nodes will be retained in the DOM tree as siblings.

setText takes a single integer parameter -- the character index at which the node is to be split.

//create a new element
$someElement =& $xmldoc->createElement('someElement');

//add a text node to the element 
$someElement->setText('Some sample text');

//echo childCount to browser
echo '$someElement has ' . $someElement->childCount . ' child nodes.';

/add a text node to the element 
$someElement->firstChild->splitText(5);

//echo childCount to browser
echo "\n<br />";
echo 'After calling splitText, $someElement now has ' . $someElement->childCount . ' child nodes.';

The result is:

$someElement has 1 child nodes.
After calling splitText, $someElement now has 2 child nodes.

The normalize method performs the opposite of the splitText method: it collapses adjacent text nodes into a single text node.

normalize can be called from any element or the DOM document itself, and is called recursively on all nodes below the calling node.

The following example splits a text node using splitNode, then uses normalize to reverse the operation:

//create a new element
$someElement =& $xmldoc->createElement('someElement');

//add a text node to the element 
$someElement->setText('Some sample text');

//echo childCount to browser
echo '$someElement has ' . $someElement->childCount . ' child nodes.';

/add a text node to the element 
$someElement->firstChild->splitText(5);

//echo childCount to browser
echo "\n<br />";
echo 'After calling splitText, $someElement now has ' . $someElement->childCount . ' child nodes.';

//call normalize on element to reverse splitText
$someElement->normalize();

//echo childCount to browser
echo "\n<br />";
echo 'After calling normalize, $someElement now has ' . $someElement->childCount . ' child nodes.';

The result is:

$someElement has 1 child nodes.
After calling splitText, $someElement now has 2 child nodes.
After calling normalize, $someElement now has 1 child nodes.

The appendData method allows you to append text to a text node, CDATA Section, or comment node. For example:

//create a new element
$someElement =& $xmldoc->createElement('someElement');

//add a text node to the element 
$someElement->setText('Some sample text');

//append more text
$someElement->firstChild->appendData(' plus more text.');

//echo to browser
echo $someElement->toNormalizedString(true);

The result is:

<someElement>Some sample text plus more text.</someElement>

The insertData method allows you to insert text into a text node, CDATA Section, or comment node, as a specified offset.

It takes two parameters: an integer indicating the insertion pont, and a string comprising the text to be inserted. For example:

//create a new element
$someElement =& $xmldoc->createElement('someElement');

//add a text node to the element 
$someElement->setText('Some sample text');

//insert some text
$someElement->firstChild->insertData(5, ' more');

//echo to browser
echo $someElement->toNormalizedString(true);

The result is:

<someElement>Some more sample text</someElement>

The replaceData method allows you to overwrite a substring of text in a text node, CDATA Section, or comment node.

It takes three parameters: an integer indicating the insertion pont, an integer specifying the number of characters from the insertion point to overwrite, and a string comprising the replacement text. For example:

//create a new element
$someElement =& $xmldoc->createElement('someElement');

//add a text node to the element 
$someElement->setText('Some sample text');

//replace some text
$someElement->firstChild->replaceData(0, 4, 'A bit of');

//echo to browser
echo $someElement->toNormalizedString(true);

The result is:

<someElement>A bit of sample text</someElement>

The deleteData method allows you to delete a substring of text in a text node, CDATA Section, or comment node.

It takes two parameters: an integer indicating the insertion pont, and an integer specifying the number of characters from the insertion point to delete. For example:

//create a new element
$someElement =& $xmldoc->createElement('someElement');

//add a text node to the element 
$someElement->setText('Some sample text');

//delete some text
$someElement->firstChild->deleteData(6, 7);

//echo to browser
echo $someElement->toNormalizedString(true);

The result is:

<someElement>Some text</someElement>

Some may argue that the DOM specification for getElementByID is too rigid for practical purposes. When parsing XHTML in particular, it is common to match on ID attributes that are not defined in such a way that DOMIT! or other non-validating parsers can effectively match on elements.

Given this, DOMIT! allows you to specify a tolerant mode for getElementByID searches. By passing in a second parameter of false, DOMIT! will match on elements with attributes of "ID" and "id".

Take the following document, for example:

<testDocument>
  <anotherElement id="12345">The containing element is NOT properly formatted for getElementByID</anotherElement>
</testDocument>

If getElementByID is called:

//instantiate and load XML
$xmldoc =& new DOMIT_Document();
$success = $xmldoc->loadXML("testDocument.xml", true);

if ($success) {
  //search for element with an ID of "12345"
  $matchingNode =& $xmldoc->getElementByID("12345");

  //echo matching node to browser if one exists
  if ($matchingNode != null) {
    echo $matchingNode->toNormalizedString(true);
  }
}

The result is:

<anotherElement xml:id="12345">The containing element is NOT properly formatted for getElementByID</anotherElement>

The getLength and item methods for a node list are identical to those for a named node map. You can use them to iterate through the node list using a for loop.

Take the previous getElementsByTagName example, which returned three nodes. You can, for instance, loop through the node list and print out the discid of each CD:

//use getElementsByTagName to gather all elements named "cd"
$matchingNodes =& $cdCollection->getElementsByTagName("cd");

//if any matching nodes are found, loop through them and print out disc id
if ($matchingNodes != null) {
  
  //get total number of nodes in the list
  $total = $matchingNodes->getLength();

  //loop through node list 
  for ($i = 0; $i < $total; $i++) {

    //get current node on list
    $currNode =& $matchingNodes->item($i);

    //echo out discid
    echo $currNode->getAttribute('discid') . "\n<br />";
  }
}

The result is:

bb0c3c0c
9b0ce70c
cf11720f

The appendNode method allows you to add a node to the end of the node list. The removeNode method allows you to remove a node from the node list.

Both methods take a single parameter -- a reference to the node being appended or removed.

To append a node to the cd node list from the above example, you could do this:

//use getElementsByTagName to gather all elements named "cd"
$matchingNodes =& $cdCollection->getElementsByTagName("cd");

//create a new node
$newNode =& $cdCollection->createElement("someElement");

//append the node to the node list
$matchingNodes->appendNode($newNode);

//echo to browser
echo $matchingNodes->toNormalizedString(true);

The result is:

<cd discid="bb0c3c0c">
  <name>Robbie Fulks</name>
  <title>Couples in Trouble</title>
</cd>
<cd discid="9b0ce70c">
  <name>Richard Thompson</name>
  <title>Mock Tudor</title>
</cd>
<cd discid="cf11720f">
  <name>Keller Williams</name>
  <title>Laugh</title>
</cd>
<someElement />

To remove a node from the cd node list from the above example, you could do this:

//use getElementsByTagName to gather all elements named "cd"
$matchingNodes =& $cdCollection->getElementsByTagName("cd");

//remove the first node from the node list
$matchingNodes->removeNode($matchingNodes->item(0));

//echo to browser
echo $matchingNodes->toNormalizedString(true);

The result is:

<cd discid="9b0ce70c">
  <name>Richard Thompson</name>
  <title>Mock Tudor</title>
</cd>
<cd discid="cf11720f">
  <name>Keller Williams</name>
  <title>Laugh</title>
</cd>

According to the DOM specification, the child nodes of an element should be kept in a node list.

However, contrary to the specification, DOMIT! uses an array rather than a node list. This is to get around a deficiency in PHP 4, in which method calls cannot be chained together as one would normally expect with an object oriented programming language.

You cannot, for instance, do this in PHP4 (although you can in PHP5)...

$myText = $xmldoc->documentElement->getChildNodes()->item(2)->getText();

...although by using an array, it is possible to burrow deeply down into a document structure without splitting your code into multiple lines:

$myText = $xmldoc->documentElement->childNodes[2]->getText();

For those who are using PHP5 and would like child nodes to be returned in node list format, the childNodesAsNodeList method can be used:

$myText = $documentElement->childNodesAsNodeList()->item(2)->getText();

The getElementsByPath method allows you to search for elements in a document that match a "path"-like pattern that you provide.

The syntax is similar to an XPath query, although the range of patterns allowed by getElementsByPath is far less sophisticated than the XPath specification permits.

The pattern takes the basic form of elementName/elementName, where the forward slash represents a parent-child relationship. Either a node list, a single node, or null is returned

getElementsByPath can be called by any node. There are three basic ways that you can form a pattern:

Let's try an example of each with our cdlibrary XML:

<?xml version="1.0"?>
<cdlibrary>
  <cd discid="bb0c3c0c">
    <name>Robbie Fulks</name>
    <title>Couples in Trouble</title>
  </cd>
  <cd discid="9b0ce70c">
    <name>Richard Thompson</name>
    <title>Mock Tudor</title>
  </cd>
  <cd discid="cf11720f">
    <name>Keller Williams</name>
    <title>Laugh</title>
  </cd>
</cdlibrary>

//use getElementsByPath to retrieve all title elements
$myNodeList =& $cdCollection->getElementsByPath("/cdlibrary/cd/title");

//echo to browser
echo $myNodeList->toNormalizedString(true);

<title>Couples in Trouble</title>
<title>Mock Tudor</title>
<title>Laugh</title>

//use getElementsByPath to retrieve all name elements which are children of 
//cd elements which are children of the cdlibrary element
$myNodeList =& $cdCollection->documentElement->getElementsByPath("cd/name");

//echo to browser
echo $myNodeList->toNormalizedString(true);

<name>Robbie Fulks</name>
<name>Richard Thompson</name>
<name>Keller Williams</name>

//use getElementsByPath to retrieve all title elements in cdlibrary
$myNodeList =& $cdCollection->getElementsByPath("//title");

//echo to browser
echo $myNodeList->toNormalizedString(true);

<title>Couples in Trouble</title>
<title>Mock Tudor</title>
<title>Laugh</title>

//use getElementsByPath to retrieve the first cd element in cdlibrary
$myElement =& $cdCollection->getElementsByPath("/cdlibrary/cd", 1);

//echo to browser
if ($myElement != null) {
  echo $myElement->toNormalizedString(true);
}

<cd discid="bb0c3c0c">
  <name>Robbie Fulks</name>
  <title>Couples in Trouble</title>
</cd>

The getElementsByAttribute method allows you to retrieve a node list of elements, each of which contain an attribute that matches the specified name and value. This is a useful improvement over the getElementByID method, since it does not require you to be bound to a narrow definition of attribute type or name.

To obtain a node list of all elements containing an attribute named 'myAttr' and a value of '3', for example, you would do this:

//get node list of elements containing myAttr="3"
$myNodeList =& $xmldoc->getElementsByAttribute('myAttr', '3');

There is a third parameter available for getElementsByAttribute, a boolean which if set to true will return the first matching element rather than an entire node list of elements:

//get first matching elements containing myAttr="3"
$myElement =& $xmldoc->getElementsByAttribute('myAttr', '3', true);

The getNodesByNodeType method allows you to search the document tree for nodes of a specific node type.

You can specify a node type using one of the following DOMIT! constants:

You must also pass in as the second parameter a context node - a node from which the search should start.

The following example returns a node list of all text nodes in the cdlibrary example:

//find all text nodes in cdlibrary
$myTextNodeList =& $cdCollection->getNodesByNodeType(DOMIT_TEXT_NODE, $cdCollection);

//echo to browser
echo $myTextNodeList->toNormalizedString(true);

The result is:

Robbie Fulks
Couples in Trouble
Richard Thompson
Mock Tudor
Keller Williams
Laugh

The getNodesByNodeValue method allows you to search the document tree for nodes of a specific node value.

This is especially useful for finding text or CDATA Section nodes containing a certain text value.

You must pass in the node value that you are searching for as well as a context node - a node from which the search should start.

The following example returns a node list of all nodes in the current document with a node value of "Robbie Fulks":

//find all text nodes with a value of "Robbie Fulks" in cdlibrary
$myTextNodeList =& $cdCollection->getNodesByNodeValue("Robbie Fulks", $cdCollection);

//get first match
$firstItem =& $myTextNodeList->item(0);

//echo parent node to browser
echo $firstItem->parentNode->toNormalizedString(true);

The result is:

<name>Robbie Fulks</name>

The toArray method converts an xml node and its children to an array.

To convert the first <cd> element of the cdlibrary example to an array, you would do this:

//convert first <cd> element to array
$myArray =& $cdCollection->documentElement->firstChild->toArray();

//echo to browser
print "<pre>";
print_r($myArray);
print "</pre>";

The result is:

Array
(
    [cd] => Array
        (
            [attributes] => Array
                (
                    [discid] => bb0c3c0c
                )

            [0] => Array
                (
                    [name] => Array
                        (
                            [attributes] => Array
                                (
                                )

                            [0] => Robbie Fulks
                        )

                )

            [1] => Array
                (
                    [title] => Array
                        (
                            [attributes] => Array
                                (
                                )

                            [0] => Couples in Trouble
                        )

                )

        )

)

The DOMIT_Utilities::fromArray method generates a node tree from an array and appends it to the specified document or node.

The convention follows that of the fromArray method in the minixml library:

//Create an array to represent a person Bob
$bob = array(
  'name' => array( 
    'first' => 'Bob',
    'last' => 'Roberts'
  ),
  'age' => 35,
  'email' => 'bob@example.com',
  'location' => array(
    'streetaddr' => '123 Skid Row',
    'city' => 'Dark City',
    'state' => 'DN',
    'country' => 'XNE',
  ),
);


//Create another array to represent a person Mary
$mary = array(
  'name' => array( 
    'first' => 'Mary',
    'last' => 'Zlipsakis'
  ),
  'age' => 94,
  'location' => array(
    'streetaddr'=> '54343 Park Ave',
    'city' => 'SmallVille',
    'state' => 'DN',
    'country' => 'XNE',
  ),
  'icecream' => 'vanilla',
);


//Create a big array that contains all our people
$xmlArray = array();
$xmlArray["people"]["person"] = array();

array_push($xmlArray["people"]["person"], $mary);
array_push($xmlArray["people"]["person"], $bob);

//instatiate a DOMIT! document
require_once('xml_domit_include.php');
$xmldoc =& new DOMIT_Document();

//require DOMIT_Utilities file
require_once('xml_domit_utilities.php');

//use fromArray to populate document
DOMIT_Utilities::fromArray($xmldoc, $xmlArray);

//echo to browser
echo $xmldoc->toNormalizedString(true);

The result is:

<people>
    <person>
        <name>
            <first>Mary</first>
            <last>Zlipsakis</last>
        </name>
        <age>94</age>
        <location>
            <streetaddr>54343 Park Ave</streetaddr>
            <city>SmallVille</city>
            <state>DN</state>
            <country>XNE</country>
        </location>
        <icecream>vanilla</icecream>
    </person>
    <person>
        <name>
            <first>Bob</first>
            <last>Roberts</last>
        </name>
        <age>35</age>
        <email>bob@example.com</email>
        <location>
            <streetaddr>123 Skid Row</streetaddr>
            <city>Dark City</city>
            <state>DN</state>
            <country>XNE</country>
        </location>
    </person>
</people>

The nodetools::parseattributes method parses an attribute string into an array of key / value pairs.

For example:

//require the nodetools library
require_once('xml_domit_nodetools.php');

//build a sample attribute string
$myAttrString = 'x="27" y="12"';

//parse into an array
$myArray = nodetools::parseattributes($myAttrString);

//echo to browser
echo "<pre>";
print_r($myArray);
echo "</pre>";

The result is:

Array
(
    [x] => 27
    [y] => 12
)

The nodetools::moveUp method moves a node to the previous index in the childNodes array.

It takes a single argument -- a reference to the node to be moved.

The following example moves the last <cd> element to the second last position:

//require the nodetools library
require_once('xml_domit_nodetools.php');

//move the node up
nodetools::moveUp($cdCollection->documentElement->lastChild);

//echo to browser
$cdCollection->toNormalizedString(true);

The result is:

<?xml version="1.0"?>
<cdlibrary>
  <cd discid="bb0c3c0c">
    <name>Robbie Fulks</name>
    <title>Couples in Trouble</title>
  </cd>
  <cd discid="cf11720f">
    <name>Keller Williams</name>
    <title>Laugh</title>
  </cd>
  <cd discid="9b0ce70c">
    <name>Richard Thompson</name>
    <title>Mock Tudor</title>
  </cd>
</cdlibrary>

The nodetools::moveDown method moves a node to the next index in the childNodes array.

It takes a single argument -- a reference to the node to be moved.

The following example moves the first <cd> element to the second position:

//require the nodetools library
require_once('xml_domit_nodetools.php');

//move the node up
nodetools::moveDown($cdCollection->documentElement->firstChild);

//echo to browser
$cdCollection->toNormalizedString(true);

The result is:

<?xml version="1.0"?>
<cdlibrary>
  <cd discid="9b0ce70c">
    <name>Richard Thompson</name>
    <title>Mock Tudor</title>
  </cd>
  <cd discid="bb0c3c0c">
    <name>Robbie Fulks</name>
    <title>Couples in Trouble</title>
  </cd>
  <cd discid="cf11720f">
    <name>Keller Williams</name>
    <title>Laugh</title>
  </cd>
</cdlibrary>

The nodetools::nodeExists method checks whether a node exists.on a given path. The path expression must conforming to the getElementsByPath syntax.

The method takes two parameters -- a reference to the calling node (the node at which the search begins) and the path expression.

To check if the first child <cd> element of the <cdlibrary> element contains a <title> element, you can do this:

//require the nodetools library
require_once('xml_domit_nodetools.php');

//check if node exists
if (nodetools::nodeExists($cdCollection, '/cdlibrary/cd/title') {
  echo "Node exists!";
}
else {
  echo "Node does NOT exist";
}

The result is:

Node exists!

The nodetools::fromPath method generates a heirarchy of elements based on a path expression.

It takes three parameters:

For example:

//require the nodetools library
require_once('xml_domit_nodetools.php');

//build node tree
$myNodes =& nodetools::fromPath($xmldoc, '/someElement/childElement', "Sample text");

//echo to browser
echo $myNodes->toNormalizedString(true);

The result is:

<someElement>
  <childElement>Sample text</childElement>
</someElement>

The XML Namespace specification proposes a mechanism whereby elements and attributes can be assigned namespaces -- or, unique identifiers that allow one to differentiate between similar tag names.

The unique identifier comes in the form of a URI (Uniform Resource Identifier), which is a convention for identifying resources on the web (an URL, or universal resource locator, is a type of URI).

For example, the namespace URI for the Dublin Core -- an XML specification for interoperable online metadata standards -- is:

http://purl.org/dc/elements/1.1/

Since the URI tends to be somewhat longish to appear frequently in your document, you can specify an abbreviation for the URI, know as the Namespace Prefix.

The namespace URI and namespace prefix are defined within your XML document, often at the level of the document element (but not necessarily so), using the keyword xmlns.

In our <individual> example from above, we might use namespaces to do the following:

<?xml version="1.0"?>
<person:individual person:gender="m"
        xmlns:person="http://www.engageinteractive.com/person/"
        xmlns:book="http://www.engageinteractive.com/book/">
  <person:name>George Henry III</person:name>
  <person:title>Duke of Fredericton</person:title>
  <person:books>
    <book:book>
      <book:title>Transcendence Through XML</book:title>
    </book:book>
  </person:books>
</person:individual>

You'll notice that in the document element node, two items have been added which appear to be attributes but which are actually Namespace Declarations. A namespace declaration:

The namespace declaration says basically that:

There are elements and /or attributes in the following XML that will be assigned the URI http://www.engageinteractive.com/person/ and these elements and/or attributes are different from elements and/or attributes that are assigned the URI http://www.engageinteractive.com/book/

It also says that:

We will use the prefix "person" as shorthand for the URI http://www.engageinteractive.com/person/, and we will use the abbreviation "book" as shorthand for the URI http://www.engageinteractive.com/book/

It is then a simple task of placing the prefixes person: and book: before all corresponding elements and attributes. A namespace aware XML parser will be able to parse and differentiate between the elements named <person:title> and <book:title>

If an XML document does not contain a namespace declaration, then it is assumed that all elements in the document belong to the default namespace. The default namespace is null unless defined by the user.

If you would like to specify a user-defined default namespace, omit the namespace prefix in your xmlns declaration:

xmlns="http://www.engageinteractive.com/this.is.a.default.namespace"

Note: Default namespaces do not apply to attributes.

When an XML document uses namespaces, the tag name of an element or attribute (i.e., the part following the namespace prefix) is referred to as its Local Name.

The local name of the <person:individual> element, for instance, is "individual".

The concatenated namespace prefix and local name are referred to as the Qualified Name, or qname.

The qualified name of <person:individual> element, for instance, is "person:individual"

The DOM specifies a number of namespace aware methods, such as getElementsByTagNameNS, which allows you to specify the qualified name of the element that you are searching for.

To enable DOMIT! to process namespace data, invoke the setNamespaceAwareness method before populating your XML document.

$xmldoc->setNamespaceAwareness(true);

The declareNamespace method allows you to make a namespace declaration at the level of the calling element.

You must specify two parameters:

The following creates a namespace declaration with a prefix of "domit" at the document element level:

$xmldoc->documentElement->declareNamespace('domit', 'http://www.engageinteractive.com/domit/');

The resulting namespace declaration would look like this:

xmlns:domit="http://www.engageinteractive.com/domit/"

The declareDefaultNamespace method allows you to make a default namespace declaration at the level of the calling element.

$xmldoc->documentElement->declareDefaultNamespace('http://www.foo.com/a.default.namespace');

The resulting ndefault amespace declaration would look like this:

xmlns="http://www.foo.com/a.default.namespace"

To reset the default namespace back to its original null value, pass in an empty string to the declareDefaultNamespace method:

$xmldoc->documentElement->declareDefaultNamespace("");

The getNamespaceDeclarationsInScope method returns an associative array of all namespace declarations that are in scope for the calling element.

//acquire array of namespace declarations in scope
$nsMap = $xmldoc->documentElement->firstChild->getNamespaceDeclarationsInScope();

//echo to browser
print "<pre>";
print_r($nsMap);
print "</pre>";

The result is:

Array
(
    [http://www.engageinteractive.com/person/] => person
    [http://www.engageinteractive.com/book/] => book
)

The getDefaultNamespaceDeclaration method returns a string containing the default namespace declaration in scope for for the calling element.

echo $xmldoc->documentElement->childNodes[2]->firstChild->getDefaultNamespaceDeclaration();

The result is an empty string:

A common problem with namespaces occurs when an element is moved to another location in a document, or copied to another DOM document.

If the node being copied is not the document element, and the namespace declarations in scope for that element are declared higher up in the DOM tree (for example, in the document element), then the namespace declarations can be lost.

In the following XML, for instance, if the <book:book> element were to be copied to another DOM document, the namespace declarations in the document element might not accompany the element:

 <?xml version="1.0"?>
<person:individual person:gender="m"
        xmlns:person="http://www.engageinteractive.com/person/"
        xmlns:book="http://www.engageinteractive.com/book/">
  <person:name>George Henry III</person:name>
  <person:title>Duke of Fredericton</person:title>
  <person:books>
    <book:book>
      <book:title>Transcendence Through XML</book:title>
    </book:book>
  </person:books>
</person:individual>

The copyNamespaceDeclarationsLocally method addresses this problem, by forcing all namespace delarations that are in scope for the element to be explicitly duplicated on the element itself.

//get reference to book:book node
$bookNode =& $xmldoc->documentElement->childNodes[2]->firstChild;

//copy namespace declarations
$bookNode->copyNamespaceDeclarationsLocally();

//echo to browser
echo $bookNode->toNormalizedString(true);

The result is:

<book:book xmlns:person="http://www.engageinteractive.com/person/" xmlns:book="http://www.engageinteractive.com/book/">
  <book:title>Transcendence Through XML</book:title>
</book:book>

The createElementNS method is used to create a namespace compliant element.

createElementNS takes two parameters:

The following example will create the <book:title> element:

//create namespace compliant element
$myElement =& $xmldoc->createElementNS('http://www.engageinteractive.com/book/', 'book:title');

//echo to browser
echo $myElement->toNormalizedString(true);

The result is:

<book:title />

Note that using the createElement method will not create an element properly when namespace awareness is enabled.

The getElementsByTagNameNS method is a namespace compliant version of getElementsByTagName. It allows you to search for elements in an XML document by specifying:

The following example matches the <book:title> element:

//find book:title element
$myNodeList =& $xmldoc->getElementsByTagNameNS('http://www.engageinteractive.com/book/', 'title');

//echo to browser
echo $myNodeList->toNormalizedString(true);

The result is:

<book:title>Transcendence Through XML</book:title>

The createAttributeNS method is the namespace equivalent of createAttribute. It enables you to create a new, namespace compliant, attribute node.

createAttributeNS takes two parameters:

The following example creates a new attribute named "book:language", with a value of "en"

//create namespace compliant attribute
$myAttr =& $xmldoc->createAttributeNS('http://www.engageinteractive.com/book/', 'language', 'en');

//echo to browser
echo $myAttr->toNormalizedString(true);

The result is:

book:language='en'

The hasAttributeNS and getAttributeNS methods are namespace compliant versions of hasAttribute and getAttribute. Both methods take as parameters:

The following example checks if an attribute named 'gender' with a namespace URI of 'http://www.engageinteractive.com/person/' exists in the document element, and echoes the value to the browser:

//set variables for namespace URI and local name
$URI = 'http://www.engageinteractive.com/person/';
$localName = 'gender';

//determine if atrribute exists
if ($xmldoc->documentElement->hasAttributeNS($URI, $localName)) {
  
  //echo to browser
  echo $xmldoc->documentElement->getAttributeNS($URI, $localName);
}

The result is:

m

The setAttributeNS method is a namespace compliant version of setAttribute. It creates a new namespace compliant attribute for the calling element, or overwrites the value of the attibute if one already exists.

setAttributeNS takes three parameters:

The following example sets a new attribute on the <book:title> element.

//find book:title element
$myNodeList =& $xmldoc->getElementsByTagNameNS('http://www.engageinteractive.com/book/', 'title');

//get first match
$myElement =& $myNodeList->item(0);

//add attribute named "book:language" to the element
$myElement->setAttributeNS('http://www.engageinteractive.com/book/', 'book:language', 'en');

//echo to browser
echo $myElement->toNormalizedString(true);

The result is:

<book:title book:language="en">Transcendence Through XML</book:title>

The getAttributeNodeNS and setAttributeNodeNS methods are namespace compliant versions of getAttributeNode and setAttributeNode.

getAttributeNodeNS takes two parameters:

setAttributeNodeNS takes a single parameter -- a reference to the node to be added/set.

The following example echoes the value of the "gender" attribute and then changes it to "f":

//get the attribute node named "gender" in the document element
$attrNode =& $xmldoc->documentElement->getAttributeNodeNS('http://www.engageinteractive.com/person/', 'gender');

//echo value of attr node
echo "original value of gender node is: " . $attrNode->getValue();

//create a new attribute node
$myAttr =& $xmldoc->createAttributeNS('http://www.engageinteractive.com/person/', 'gender', 'f');

//overwrite existing attr with new one
$xmldoc->documentElement->setAttributeNodeNS();

//echo to browser
echo $xmldoc->documentElement->toNormalizedString(true);

The result is:

<person:individual person:gender="f"
        xmlns:person="http://www.engageinteractive.com/person/"
        xmlns:book="http://www.engageinteractive.com/book/">
  <person:name>George Henry III</person:name>
  <person:title>Duke of Fredericton</person:title>
  <person:books>
    <book:book>
      <book:title>Transcendence Through XML</book:title>
    </book:book>
  </person:books>
</person:individual>

The removeAttributeNS method is the namespace counterpart to removeAttribute. It enabled you to remove an attribute from an element.

removeAttributeNS takes two parameters:

The following example removes the "gender" attribute from the document element:

//remove "gender" attribute from document element
$xmldoc->documentElement->removeAttributeNS('http://www.engageinteractive.com/person/', 'gender');

//echo to browser
echo $xmldoc->documentElement->toNormalizedString(true);

The result is:

<person:individual
        xmlns:person="http://www.engageinteractive.com/person/"
        xmlns:book="http://www.engageinteractive.com/book/">
  <person:name>George Henry III</person:name>
  <person:title>Duke of Fredericton</person:title>
  <person:books>
    <book:book>
      <book:title>Transcendence Through XML</book:title>
    </book:book>
  </person:books>
</person:individual>