XXV. DOM XML functions

Introduction

Warning

This extension is EXPERIMENTAL. The behaviour of this extension -- including the names of its functions and anything else documented about this extension -- may change without notice in a future release of PHP. Use this extension at your own risk.

The domxml extension has been overhauled in PHP 4.3.0 to provide a better compliance with the DOM standard. The extension still contains many old functions, but they should not be used anymore. Especially those non object oriented functions should be avoided.

The extension allows you to operate on an XML document with the DOM API. It also provides a function domxml_xmltree() to turn the complete XML document into a tree of PHP objects. Currently this tree should be considered read-only - you can modify it but this would not make any sense since DomDocument_dump_mem() cannot be applied to it. Therefore, if you want to read an XML file and write a modified version use the DomDocument_create_element(), DomDocument_create_text_node(), set_attribute(), etc. and finally DomDocument_dump_mem() functions.

Requirements

This extension make use of the GNOME xml library. Download and install this library. You will need at least libxml-2.4.14

Installation

This extension is only available if PHP was configured with --with-dom=[DIR].

Deprecated functions

There are quite a few functions that do not fit into the DOM standard and should not be used anymore as listed in the following table. The function DomNode_append_child() has changed its behaviour. It now actually adds a child and not a sibling. If this breaks your application use the non DOM function DomNode_append_sibling().

Table 1. Deprecated functions and their replacements

Old functionNew function
xmldocdomxml_open_mem()
xmldocfiledomxml_open_file()
domxml_new_xmldocdomxml_new_doc()
domxml_dump_memDomDocument_dump_mem()
domxml_dump_mem_fileDomDocument_dump_file()
DomDocument_dump_mem_fileDomDocument_dump_file()
DomDocument_add_rootDomDocument_create_element() followed by DomNode_append_child()
DomDocument_dtdDomDocument_doctype()
DomDocument_rootDomDocument_document_element()
DomDocument_childrenDomNode_child_nodes()
DomDocument_imported_nodeNo replacement.
DomNode_add_childCreate a new node with e.g. DomDocument_create_element() und add it with DomNode_append_child().
DomNode_childrenDomNode_child_nodes()
DomNode_parentDomNode_parent_node()
DomNode_new_childCreate a new node with e.g. DomDocument_create_element() und add it with DomNode_append_child().
DomNode_set_contentCreate a new node with e.g. DomDocument_create_text_node() und add it with DomNode_append_child().
DomNode_get_contentContent is just a text node and can be accessed with DomNode_child_nodes().
DomNode_set_contentContent is just a text node and can be added with DomNode_append_child().

Predefined Constants

The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.

Table 2. XML constants

ConstantValueDescription
XML_ELEMENT_NODE (integer) 1Node is an element
XML_ATTRIBUTE_NODE (integer) 2Node is an attribute
XML_TEXT_NODE (integer) 3Node is a piece of text
XML_CDATA_SECTION_NODE (integer) 4 
XML_ENTITY_REF_NODE (integer) 5 
XML_ENTITY_NODE (integer) 6Node is an entity like  
XML_PI_NODE (integer) 7Node is a processing instruction
XML_COMMENT_NODE (integer) 8Node is a comment
XML_DOCUMENT_NODE (integer) 9Node is a document
XML_DOCUMENT_TYPE_NODE (integer) 10 
XML_DOCUMENT_FRAG_NODE (integer) 11 
XML_NOTATION_NODE (integer) 12 
XML_GLOBAL_NAMESPACE (integer) 1 
XML_LOCAL_NAMESPACE (integer) 2 
XML_HTML_DOCUMENT_NODE (integer)   
XML_DTD_NODE (integer)   
XML_ELEMENT_DECL_NODE (integer)   
XML_ATTRIBUTE_DECL_NODE (integer)   
XML_ENTITY_DECL_NODE (integer)   
XML_NAMESPACE_DECL_NODE (integer)   
XML_ATTRIBUTE_CDATA (integer)   
XML_ATTRIBUTE_ID (integer)   
XML_ATTRIBUTE_IDREF (integer)   
XML_ATTRIBUTE_IDREFS (integer)   
XML_ATTRIBUTE_ENTITY (integer)   
XML_ATTRIBUTE_NMTOKEN (integer)   
XML_ATTRIBUTE_NMTOKENS (integer)   
XML_ATTRIBUTE_ENUMERATION (integer)   
XML_ATTRIBUTE_NOTATION (integer)   
XPATH_UNDEFINED (integer)   
XPATH_NODESET (integer)   
XPATH_BOOLEAN (integer)   
XPATH_NUMBER (integer)   
XPATH_STRING (integer)   
XPATH_POINT (integer)   
XPATH_RANGE (integer)   
XPATH_LOCATIONSET (integer)   
XPATH_USERS (integer)   
XPATH_NUMBER (integer)   

Classes

The API of the module follows the DOM Level 2 standard as close as possible. Consequently the API is fully object oriented. It is a good idea to have the DOM standard available when using this module. Though the API is object oriented there are many functions which can be called in a non-object oriented way by passing the object to operate on as the first argument. These function are mainly to retain compatibilty to older versions of the extension but are not encouraged to use anymore in new developments.

This API differs from the official DOM API in two points. First, all class attributes are implemented as functions with the same name and secondly the function names follow the PHP naming convention. This means that a DOM function lastChild() will be written as last_child().

This module defines a number of classes, which are listed — including their method — in the following tables. Classes with an equivalent in the DOM Standard are named DOMxxx.

Table 3. List of classes

Class nameParent classes
DomAttributeDomNode
DomCDataDomNode
DomCommentDomCData : DomNode
DomDocumentDomNode
DomDocumentTypeDomNode
DomElementDomNode
DomEntityDomNode
DomEntityReferenceDomNode
DomProcessingInstructionDomNode
DomTextDomCData : DomNode
ParserCurrently still called DomParser
XPathContext 

Table 4. DomDocument class (DomDocument : DomNode)

Method nameFunction nameRemark
doctypeDomDocument_doctype() 
document_elemnentDomDocument_document_element() 
create_elementDomDocument_create_element() 
create_text_nodeDomDocument_create_text_node() 
create_commentDomDocument_create_comment() 
create_cdata_sectionDomDocument_create_cdata_section() 
create_processing_instructionDomDocument_create_processing_instruction() 
create_attributeDomDocument_create_attribute() 
create_entity_referenceDomDocument_create_entity_reference() 
get_elements_by_tagnameDomDocument_get_elements_by_tagname() 
get_element_by_idDomDocument_get_element_by_id() 
dump_memDomDocument_dump_mem()not DOM standard
dump_fileDomDocument_dump_file()not DOM standard
html_dump_memDomDocument_html_dump_mem()not DOM standard
xpath_initxpath_initnot DOM standard
xpath_new_contextxpath_new_contextnot DOM standard
xptr_new_contextxptr_new_contextnot DOM standard

Table 5. DomElement class (DomElement : DomNode)

Method nameFunction nameRemark
tagnameDomElement_tagname() 
get_attributeDomElement_get_attribute() 
set_attributeDomElement_set_attribute() 
remove_attributeDomElement_remove_attribute() 
get_attribute_nodeDomElement_get_attribute_node() 
get_elements_by_tagnameDomElement_get_elements_by_tagname() 
has_attributeDomElement_has_attribute() 

Table 6. DomNode class

Method nameRemark
DomNode_node_name() 
DomNode_node_value() 
DomNode_node_type() 
DomNode_last_child() 
DomNode_first_child() 
DomNode_child_nodes() 
DomNode_previous_sibling() 
DomNode_next_sibling() 
DomNode_parent_node() 
DomNode_owner_document() 
DomNode_insert_before() 
DomNode_append_child() 
DomNode_append_sibling()Not in DOM standard. This function emulates the former behaviour of DomNode_append_child().
DomNode_remove_child() 
DomNode_has_child_nodes() 
DomNode_has_attributes() 
DomNode_clone_node() 
DomNode_attributes() 
DomNode_unlink_node()Not in DOM standard
DomNode_replace_node()Not in DOM standard
DomNode_set_content()Not in DOM standard, deprecated
DomNode_get_content()Not in DOM standard, deprecated
DomNode_dump_node()Not in DOM standard
DomNode_is_blank_node()Not in DOM standard

Table 7. DomAttribute class (DomAttribute : DomNode)

Method name Remark
nameDomAttribute_name() 
valueDomAttribute_value() 
specifiedDomAttribute_specified() 

Table 8. DomProcessingInstruction class (DomProcessingInstruction : DomNode)

Method nameFunction nameRemark
targetDomProcessingInstruction_target() 
dataDomProcessingInstruction_data() 

Table 9. Parser class

Method nameFunction nameRemark
add_chunkParser_add_chunk() 
endParser_end() 

Table 10. XPathContext class

Method nameFunction nameRemark
evalXPathContext_eval() 
eval_expressionXPathContext_eval_expression() 
register_nsXPathContext_register_ns() 

Table 11. DomDocumentType class (DomDocumentType : DomNode)

Method nameFunction nameRemark
nameDomDocumentType_name() 
entitiesDomDocumentType_entities() 
notationsDomDocumentType_notations() 
public_idDomDocumentType_public_id() 
system_idDomDocumentType_system_id() 
internal_subsetDomDocumentType_internal_subset() 

The classes DomDtd is derived from DomNode. DomComment is derived from DomCData

Examples

Many examples in this reference require an XML string. Instead of repeating this string in any example it will be put into a file and be included by each example. This include file is shown in the following example section. You could also create an XML document read it with DomDocument_open_file().

Example 1. Include file example.inc with XML string

<?php
$xmlstr = "<?xml version='1.0' standalone='yes'?>
<!DOCTYPE chapter SYSTEM '/share/sgml/Norman_Walsh/db3xml10/db3xml10.dtd'
[ <!ENTITY sp \"spanish\">
]>
<!-- lsfj  -->
<chapter language='en'><title language='en'>Title</title>
 <para language='ge'>
  &amp;sp;
  <!-- comment -->
  <informaltable ID='findme' language='&amp;sp;'>
   <tgroup cols='3'>
    <tbody>
     <row><entry>a1</entry><entry
morerows='1'>b1</entry><entry>c1</entry></row>
<row><entry>a2</entry><entry>c2</entry></row>
     <row><entry>a3</entry><entry>b3</entry><entry>c3</entry></row>
    </tbody>
   </tgroup>
  </informaltable>
 </para>
</chapter>";
?>

Table of Contents
DomAttribute->name --  Returns name of attribute
DomAttribute->specified --  Checks if attribute is specified
DomAttribute->value --  Returns value of attribute
DomDocument->add_root [deprecated] --  Adds a root node
DomDocument->create_attribute --  Create new attribute
DomDocument->create_cdata_section --  Create new cdata node
DomDocument->create_comment --  Create new comment node
DomDocument->create_element_ns --  Create new element node with an associated namespace
DomDocument->create_element --  Create new element node
DomDocument->create_entity_reference -- 
DomDocument->create_processing_instruction --  Creates new PI node
DomDocument->create_text_node --  Create new text node
DomDocument->doctype --  Returns the document type
DomDocument->document_element --  Returns root element node
DomDocument->dump_file --  Dumps the internal XML tree back into a file
DomDocument->dump_mem --  Dumps the internal XML tree back into a string
DomDocument->get_element_by_id --  Searches for an element with a certain id
DomDocument->get_elements_by_tagname -- 
DomDocument->html_dump_mem --  Dumps the internal XML tree back into a string as HTML
DomDocument->xinclude --  Substitutes XIncludes in a DomDocument Object.
DomDocumentType->entities --  Returns list of entities
DomDocumentType->internal_subset --  Returns internal subset
DomDocumentType->name --  Returns name of document type
DomDocumentType->notations --  Returns list of notations
DomDocumentType->public_id --  Returns public id of document type
DomDocumentType->system_id --  Returns system id of document type
DomElement->get_attribute_node --  Returns value of attribute
DomElement->get_attribute --  Returns value of attribute
DomElement->get_elements_by_tagname --  Adds new attribute
DomElement->has_attribute --  Adds new attribute
DomElement->remove_attribute --  Adds new attribute
DomElement->set_attribute --  Adds new attribute
DomElement->tagname --  Returns name of element
DomNode->add_namespace --  Adds a namespace declaration to a node.
DomNode->append_child --  Adds new child at the end of the children
DomNode->append_sibling --  Adds new sibling to a node
DomNode->attributes --  Returns list of attributes
DomNode->child_nodes --  Returns children of node
DomNode->clone_node --  Clones a node
DomNode->dump_node --  Dumps a single node
DomNode->first_child --  Returns first child of node
DomNode->get_content --  Gets content of node
DomNode->has_attributess --  Checks if node has attributes
DomNode->has_child_nodes --  Checks if node has children
DomNode->insert_before --  Inserts new node as child
DomNode->is_blank_node --  Checks if node is blank
DomNode->last_child --  Returns last child of node
DomNode->next_sibling --  Returns the next sibling of node
DomNode->node_name --  Returns name of node
DomNode->node_type --  Returns type of node
DomNode->node_value --  Returns value of a node
DomNode->owner_document --  Returns the document this node belongs to
DomNode->parent_node --  Returns the parent of the node
DomNode->prefix --  Returns name space prefix of node
DomNode->previous_sibling --  Returns the previous sibling of node
DomNode->remove_child --  Removes child from list of children
DomNode->replace_child --  Replaces a child
DomNode->replace_node --  Replaces node
DomNode->set_content --  Sets content of node
DomNode->set_name --  Sets name of node
DomNode->set_namespace --  Sets namespace of a node.
DomNode->unlink_node --  Deletes node
DomProcessingInstruction->data --  Returns data of pi node
DomProcessingInstruction->target --  Returns target of pi node
DomXsltStylesheet->process --  Applies the XSLT-Transformation on a DomDocument Object.
domxml_new_doc --  Creates new empty XML document
domxml_open_file -- Creates a DOM object from XML file
domxml_open_mem -- Creates a DOM object of an XML document
domxml_version --  Get XML library version
domxml_xmltree --  Creates a tree of PHP objects from an XML document
domxml_xslt_stylesheet_doc --  Creates a DomXsltStylesheet Object from a DomDocument Object.
domxml_xslt_stylesheet_file --  Creates a DomXsltStylesheet Object from a xsl document in a file.
domxml_xslt_stylesheet --  Creates a DomXsltStylesheet Object from a xml document in a string.
xpath_eval_expression --  Evaluates the XPath Location Path in the given string
xpath_eval --  Evaluates the XPath Location Path in the given string
xpath_new_context --  Creates new xpath context
xptr_eval --  Evaluate the XPtr Location Path in the given string
xptr_new_context --  Create new XPath Context