diff --git a/functions/domxml.xml b/functions/domxml.xml index 7fae3af269..f9ef9ec2ab 100644 --- a/functions/domxml.xml +++ b/functions/domxml.xml @@ -1,421 +1,691 @@ - + DOM XML functions DOM XML + + + Introduction &warn.experimental; - - This documentation is not finished yet. Don't start to translate it - or use it as a programming reference (steinm@php.net). - - + + This documentation is not finished yet. Don't start to translate it + or use it as a programming reference (steinm@php.net). + + + The extension allows you to operate on an XML document with the DOM API. + It also provides a function 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 dumpmem 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, + set_attribute, etc. and finally + dumpmem functions. + + + + + Requirements + These functions are only available if PHP was configured with , using the GNOME xml library. You will need at least libxml-2.2.7 These functions have been added in PHP 4. - - - The extension allows you to operate on an XML document with the DOM API. - It also provides a function 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 dumpmem cannot be - applied to it. Therefore, if you want to read an XML file and write - a modified version use the add_node, - set_attribute, etc. and finally - dumpmem functions. - - - This module defines the following constants: - - - XML constants - - - - Constant - Value - Description - - - - - XML_ELEMENT_NODE - 1 - Node is an element - - - XML_ATTRIBUTE_NODE - 2 - Node is an attribute - - - XML_TEXT_NODE - 3 - Node is a piece of text - - - XML_CDATA_SECTION_NODE - 4 - - - - XML_ENTITY_REF_NODE - 5 - - - - XML_ENTITY_NODE - 6 - Node is an entity like   - - - XML_PI_NODE - 7 - Node is a processing instruction - - - XML_COMMENT_NODE - 8 - Node is a comment - - - XML_DOCUMENT_NODE - 9 - Node is a document - - - XML_DOCUMENT_TYPE_NODE - 10 - - - - XML_DOCUMENT_FRAG_NODE - 11 - - - - XML_NOTATION_NODE - 12 - - - - XML_GLOBAL_NAMESPACE - 1 - - - - XML_LOCAL_NAMESPACE - 2 - - - - -
- - Each function in this extension can be used in two ways. In a non-object - oriented way by passing the object to apply the function to as a first - argument, or in an object oriented way by calling the function as a method - of an object. This documentation describes the non-object oriented - functions, though you get the object methods by skipping the prefix - "domxml_". - - - This module defines a number of classes, which are listed — - including their - properties and method — in the following table. - - - - DomDocument class (methods) - - - - Method name - Function name - Description - - - - - root - domxml_root - - - - children - domxml_children - - - - add_root - domxml_add_root - - - - dtd - domxml_intdtd - - - - dumpmem - domxml - - - - xpath_init - xpath_init - - - - xpath_new_context - xpath_new_context - - - - xptr_new_context - xptr_new_context - - - - -
- + + - - - DomDocument class (attributes) - - - - Name - Type - Description - - - - - doc - class DomDocument - The object itself - - - name - string - - - - url - string - - - - version - string - Version of XML - - - encoding - string - - - - standalone - long - 1 if the file is a standalone version - - - type - long - One of the constants in table ... - - - compression - long - 1 if the file is compressed - - - charset - long - - - - -
- + + Constants + + This module defines the following constants: + + + XML constants + + + + Constant + Value + Description + + + + + XML_ELEMENT_NODE + 1 + Node is an element + + + XML_ATTRIBUTE_NODE + 2 + Node is an attribute + + + XML_TEXT_NODE + 3 + Node is a piece of text + + + XML_CDATA_SECTION_NODE + 4 + + + + XML_ENTITY_REF_NODE + 5 + + + + XML_ENTITY_NODE + 6 + Node is an entity like   + + + XML_PI_NODE + 7 + Node is a processing instruction + + + XML_COMMENT_NODE + 8 + Node is a comment + + + XML_DOCUMENT_NODE + 9 + Node is a document + + + XML_DOCUMENT_TYPE_NODE + 10 + + + + XML_DOCUMENT_FRAG_NODE + 11 + + + + XML_NOTATION_NODE + 12 + + + + XML_GLOBAL_NAMESPACE + 1 + + + + XML_LOCAL_NAMESPACE + 2 + + + + +
+ - - - DomNode class (methods) - - - - Name - PHP name - Description - - - - - lastchild - domxml_last_child - - - - children - domxml_children - - - - parent - domxml_parent - - - - new_child - domxml_new_child - - - - get_attribute - domxml_get_attribute - - - - set_attribute - domxml_set_attribute - - - - attributes - domxml_attributes - - - - node - domxml_node - - - - set_content - domxml_set_content - - - - -
- + + 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. + + + + + List of classes + + + + Class name + Parent classes + + + + + DomAttribute + DomNode + + + DomCData + DomNode + + + DomComment + DomCData : DomNode + + + DomDocument + DomNode + + + DomDocumentType + DomNode + + + DomElement + DomNode + + + DomEntity + DomNode + + + DomEntityReference + DomNode + + + DomProcessingInstruction + DomNode + + + DomText + DomCData : DomNode + + + DomParser + + + + XPathContext> + + + + +
+ - - - DomNode class (attributes) - - - - Name - Type - Description - - - - - node - class DomNode - The object itself - - - type - long - - - - tagname - string - - - - content - string - - - - -
- + + + DomDocument class (DomDocument : DomNode) + + + + Method name + Function name + Description + + + + + doctype + DomDocument_doctype + Returns the document type + + + document_elemnent + DomDocument_document_element + + + + create_element + DomDocument_create_element + + + + create_text_node + DomDocument_create_text_node + + + + create_comment + DomDocument_create_comment + + + + create_cdata_section + DomDocument_create_cdata_section + + + + create_processing_instruction + DomDocument_create_processing_instruction + + + + create_attribute + DomDocument_create_attribute + + + + create_entity_reference + DomDocument_create_entity_reference + + + + get_elements_by_tagname + DomDocument_get_elements_by_tagname + + + + get_element_by_id + DomDocument_get_element_by_id + + + + add_root + domxml_add_root + + + + dtd + domxml_intdtd + + + + dumpmem + domxml + + + + xpath_init + xpath_init + + + + xpath_new_context + xpath_new_context + + + + xptr_new_context + xptr_new_context + + + + +
+ + + + DomElement class (DomElement : DomNode) + + + + Method name + Function name + Description + + + + + tagname + DomElement_tagname + + + + get_attribute + DomElement_get_attribute + + + + set_attribute + DomElement_set_attribute + + + + remove_attribute + DomElement_remove_attribute + + + + get_attribute_node + DomElement_get_attribute_node + + + + set_attribute_node + DomElement_set_attribute_node + + + + get_elements_by_tagname + DomElement_get_elements_by_tagname + + + + has_attribute + DomElement_has_attribute + + + + +
+ + + + + DomNode class + + + + Method name + Description + + + + + 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_has_child_nodes + + + + DomNode_has_attributes + + + + new_child + Not in DOM standard + + + get_attribute + Not in DOM standard + + + set_attribute + Not in DOM standard + + + DomNode_attributes + + + + node + Not in DOM standard + + + set_content + Not in DOM standard + + + +
+ + + + + DomAttribute class (DomAttribute : DomNode) + + + + Method name + + Description + + + + + name + DomAttribute_name + + + + value + DomAttribute_value + + + + specified + DomAttribute_specified + + + + +
+ + + + + DomProcessingInstruction class (DomProcessingInstruction : DomNode) + + + + Method name + Function name + Description + + + + + target + DomProcessingInstruction_target + + + + data + DomProcessingInstruction_data + + + + +
+ + + + + DomParser class + + + + Method name + Function name + Description + + + + + add_chunk + DomParser_add_chunk + + + + end + DomParser_end + + + + +
+ + + + + XPathContext class + + + + Method name + Function name + Description + + + + + eval + XPathContext_eval + + + + eval_expression + XPathContext_eval_expression + + + + register_ns + XPathContext_register_ns + + + + +
+ + + + + DomDocumentType class (DomDocumentType : DomNode) + + + + Method name + Function name + Description + + + + + name + DomDocumentType_name + + + + entities + DomDocumentType_entities + + + + notations + DomDocumentType_notations + + + + public_id + DomDocumentType_public_id + + + + system_id + DomDocumentType_system_id + + + + internal_subset + DomDocumentType_internal_subset + + + + +
+ + + + The classes DomDtd is derived from DomNode. DomComment is derived from + DomCData + + + + + Examples + + Many examples in this reference require a 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. + + Include file example.inc with xml string + + + +]> + +Title + + &sp; + + + + + a1b1c1 +a2c2 + a3b3c3 + + + + +"; +?> +]]> + + + + - - - - - - - - - - - xmldoc @@ -467,7 +737,7 @@ xmltree - Creates a tree of PHP objects from XML document + Creates a tree of PHP objects from an XML document @@ -490,62 +760,65 @@ - + + + - domxml_root + DomDocument->doctype + + Returns the document type + + + + Description + + objectDomDocument->doctype + + + + This function returns an object of class + DomDocumentType. In versions of + PHP before 4.3 this has been the class Dtd, + but the DOM Standard does not know such a class. + + + See also the methods of class DomDocumentType. + + + + + + + DomDocument->document_element Returns root element node Description - - objectdomxml_root - objectdoc - - &warn.experimental.func; + + objectDomDocument->document_element + + - domxml_root takes one argument, an object of class - "Dom document", and returns the root element node. There are actually - other possible nodes like comments which are currently disregarded. + This function returns the root element node of a document. The following example returns just the element with name CHAPTER and - prints it. The other root node -- the comment -- is not returned. + prints it. The other node -- the comment -- is not returned. Retrieving root element - -]> - -Title - - &sp; - - - - - a1b1c1 -a2c2 - a3b3c3 - - - - -"; +include("example.inc"); if(!$dom = xmldoc($xmlstr)) { echo "Error while parsing the document\n"; exit; } -$root = $dom->root(); -/* or $root = domxml_root($dom); */ +$root = $dom->document_element(); print_r($root); ?> ]]> @@ -555,6 +828,297 @@ print_r($root); + + + DomDocument->create_element + + Create new element node + + + + Description + + objectDomDocument->create_element + stringname + + + This function returns a new instance of class + DomElement. The tag name of the element is the + value of the passed parameter. This node will not show up in the + document unless it is inserted with e.g. + DomNode_append_child. + + + The return value is false if an error occured. + + + See also DomNode_append_child, + DomDocument_create_text, + DomDocument_create_comment, + DomDocument_create_attribute, + DomDocument_create_processing_instruction, + DomDocument_create_entity_reference, + DomNode_insert_before. + + + + + + + DomDocument->create_text_node + + Create new text node + + + + Description + + objectDomDocument->create_text_node + stringcontent + + + This function returns a new instance of class + DomText. The content of the text is the value of + the passed + parameter. This node will not show up in the + document unless it is inserted with e.g. + DomNode_append_child. + + + The return value is false if an error occured. + + + See also DomNode_append_child, + DomDocument_create_element, + DomDocument_create_comment, + DomDocument_create_text, + DomDocument_create_attribute, + DomDocument_create_processing_instruction, + DomDocument_create_entity_reference, + DomNode_insert_before. + + + + + + + DomDocument->create_comment + + Create new comment node + + + + Description + + objectDomDocument->create_comment + stringcontent + + + This function returns a new instance of class + DomComment. The content of the comment is the + value of the passed parameter. This node will not show up in the + document unless it is inserted with e.g. + DomNode_append_child. + + + The return value is false if an error occured. + + + See also DomNode_append_child, + DomDocument_create_element, + DomDocument_create_text, + DomDocument_create_attribute, + DomDocument_create_processing_instruction, + DomDocument_create_entity_reference, + DomNode_insert_before. + + + + + + + DomDocument->create_cdata_section + + Create new cdata node + + + + Description + + stringDomDocument->create_cdata_section + stringcontent + + + This function returns a new instance of class + DomCData. The content of the cdata is the + value of the passed parameter. This node will not show up in the + document unless it is inserted with e.g. + DomNode_append_child. + + + The return value is false if an error occured. + + + See also DomNode_append_child, + DomDocument_create_element, + DomDocument_create_text, + DomDocument_create_attribute, + DomDocument_create_processing_instruction, + DomDocument_create_entity_reference, + DomNode_insert_before. + + + + + + + DomDocument->create_processing_instruction + + Creates new PI node + + + + Description + + stringDomDocument->create_processing_instruction + stringcontent + + + This function returns a new instance of class + DomCData. The content of the pi is the + value of the passed parameter. This node will not show up in the + document unless it is inserted with e.g. + DomNode_append_child. + + + The return value is false if an error occured. + + + See also DomNode_append_child, + DomDocument_create_element, + DomDocument_create_text, + DomDocument_create_cdata_section, + DomDocument_create_attribute, + DomDocument_create_entity_reference, + DomNode_insert_before. + + + + + + + DomDocument->create_attribute + + Create new attribute + + + + Description + + objectDomDocument->create_attribute + stringname + stringvalue + + + This function returns a new instance of class + DomAttribute. The name of the attribute is the + value of the first parameter. The value of the attribute is the value of + the second parameter. This node will not show up in the + document unless it is inserted with e.g. + DomNode_append_child. + + + The return value is false if an error occured. + + + See also DomNode_append_child, + DomDocument_create_element, + DomDocument_create_text, + DomDocument_create_cdata_section, + DomDocument_create_processing_instruction, + DomDocument_create_entity_reference, + DomNode_insert_before. + + + + + + + DomDocument->create_entity_reference + + + + + Description + + objectDomDocument->create_entity_reference + stringcontent + + + This function returns a new instance of class + DomEntityReference. The content of the entity + reference is the + value of the passed parameter. This node will not show up in the + document unless it is inserted with e.g. + DomNode_append_child. + + + The return value is false if an error occured. + + + See also DomNode_append_child, + DomDocument_create_element, + DomDocument_create_text, + DomDocument_create_cdata_section, + DomDocument_create_processing_instruction, + DomDocument_create_attribute, + DomNode_insert_before. + + + + + + + DomDocument->get_elements_by_tagname + + + + + Description + + arrayDomDocument->get_elements_by_tagname + stringname + + + + + See also domxml_add_root + + + + + + + DomDocument->get_element_by_id + + + + + Description + + objectDomDocument->get_element_by_id + stringid + + + + + See also domxml_add_root + + + + + + domxml_add_root @@ -842,6 +1406,934 @@ $children = $head->children(); + + + + + DomElement->tagname + + Returns name of element + + + + Description + + stringDomElement->tagname + + + + &warn.undocumented.func; + + + + + + + DomElement->get_attribute + + Returns value of attribute + + + + Description + + objectDomElement->get_attribute + stringname + + + &warn.undocumented.func; + + + + + + + DomElement->set_attribute + + Adds new attribute + + + + Description + + boolDomElement->set_attribute + stringname + stringvalue + + + &warn.undocumented.func; + + + + + + + DomElement->get_attribute_node + + Returns value of attribute + + + + Description + + objectDomElement->get_attribute_node + objectattr + + + &warn.undocumented.func; + + + + + + + DomElement->set_attribute_node + + Adds new attribute + + + + Description + + boolDomElement->set_attribute_node + objectattr + + + &warn.undocumented.func; + + + + + + + DomElement->remove_attribute + + Adds new attribute + + + + Description + + boolDomElement->remove_attribute + stringname + + + &warn.undocumented.func; + + + + + + + DomElement->get_elements_by_tagname + + Adds new attribute + + + + Description + + boolDomElement->get_elements_by_tagname + stringname + + + &warn.undocumented.func; + + + + + + + DomElement->has_attribute + + Adds new attribute + + + + Description + + boolDomElement->has_attribute + stringname + + + &warn.undocumented.func; + + + + + + + + + + + DomNode->attributes + + Returns list of attributes + + + + Description + + arrayDomNode->attributes + + + + This function only returns an array of attributes if the node is of + type XML_ELEMENT_NODE. + + + + + + + DomNode->node_name + + Returns name of node + + + + Description + + stringDomNode->node_name + + + + Returns name of the node. The name has different meanings + for the different types of nodes as illustrated in the following table. + + Meaning of value + + + + Type + Meaning + + + + + DomAttribute + value of attribute + + + DomAttribute + + + + DomCDataSection + #cdata-section + + + DomComment + #comment + + + DomDocument + #document + + + DomDocumentType + document type name + + + DomElement + tag name + + + DomEntity + name of entity + + + DomEntityReference + name of entity reference + + + DomNotation + notation name + + + DomProcessingInstruction + target + + + DomText + #text + + + +
+ + + + + + + DomNode->node_value + + Returns value of a node + + + + Description + + stringDomNode->node_value + + + + Returns value of the node. The value has different meanings + for the different types of nodes as illustrated in the following table. + + Meaning of value + + + + Type + Meaning + + + + + DomAttribute + value of attribute + + + DomAttribute + + + + DomCDataSection + content + + + DomComment + content of comment + + + DomDocument + null + + + DomDocumentType + null + + + DomElement + null + + + DomEntity + null + + + DomEntityReference + null + + + DomNotation + null + + + DomProcessingInstruction + entire content without target + + + DomText + content of text + + + +
+ + + + + + + DomNode->node_type + + Returns type of node + + + + Description + + intDomNode->node_type + + + + Returns the type of the node. All possible types are listed in + the table in the introduction. + + + + + + + DomNode->last_child + + Returns last child of node + + + + Description + + objectDomNode->last_child + + + + Returns the last child of the node. + + + See also DomNode_first_child, + DomNode_next_sibling, + DomNode_previous_sibling. + + + + + + + DomNode->first_child + + Returns first child of node + + + + Description + + boolDomNode->first_child + + + + Returns the first child of the node. + + + See also DomNode_last_child, + DomNode_next_sibling, + DomNode_previous_sibling. + + + + + + + DomNode->child-nodes + + Returns children of node + + + + Description + + arrayDomNode->child_nodes + + + + Returns all children of the node. + + + See also DomNode_next_sibling, + DomNode_previous_sibling. + + + + + + + DomNode->previous_sibling + + Returns the previous sibling of node + + + + Description + + objectDomNode->previous_sibling + + + + This function returns the previous sibling of the current node. + + + See also DomNode_next_sibling. + + + + + + + DomNode->next_sibling + + Returns the next sibling of node + + + + Description + + objectDomNode->next_sibling + + + + This function returns the next sibling of the current node. If there is + no next sibling it returns false. You can use this function to iterate + over all children of a node as shown in the example. + + + + Iterate over children + +get_elements_by_tagname("tbody"); +$element = $elements[0]; +$child = $element->first_child(); + +while($child) { + print_r($child); + $child = $child->next_sibling(); +} +?> +]]> + + + + + See also DomNode_previous_sibling. + + + + + + + DomNode->parent_node + + Returns the parent of the node + + + + Description + + objectDomNode->parent_node + + + + This function returns the parent node. + + + The following example will show two identical lists of children. + + Finding the document of a node + +create_element("para"); +$node = $doc->append_child($node); +$children = $doc->children(); +print_r($children); + +$doc2 = $node->parent_node(); +$children = $doc2->children(); +print_r($children); +?> +]]> + + + + + + + + + DomNode->owner_document + + Returns the document this node belongs to + + + + Description + + objectDomNode->owner_document + + + + This function returns the document the current node belongs to. + + + The following example will create two identical lists of children. + + Finding the document of a node + +create_element("para"); +$node = $doc->append_child($node); +$children = $doc->children(); +print_r($children); + +$doc2 = $node->owner_document(); +$children = $doc2->children(); +print_r($children); +?> +]]> + + + + + See also DomNode_insert_before. + + + + + + + DomNode->insert_before + + Inserts new node as child + + + + Description + + objectDomNode->insert_before + objectnewnode + objectrefnode + + + This function inserts the new node newnode right + before the node refnode. + The return value is the + appended child. If you plan to do further modifications on the appended + child you must use the returned node. + + + See also DomNode_append_child. + + + + + + + DomNode->append_child + + Adds new child at the end of the children + + + + Description + + nodeDomNode->append_child + objectnewnode + + + This functions appends a child to an existing list of children or creates + a new child. The child can be created with e.g. + DomDocument_create_element, + DomDocument_create_text etc. The return value is the + appended child. If you plan to do further modifications on the appended + child you must use the returned node. + + + + Adding a child + +create_element("para"); +$node = $doc->append_child($node); +$node->set_attribute("align", "left"); +?> +]]> + + + + + See also DomNode_insert_before. + + + + + + + DomNode->has_child_nodes + + Checks if node has children + + + + Description + + boolDomNode->has_child_nodes + + + + This function checks if the node has children. + + + See also DomNode_child_nodes. + + + + + + + DomNode->has_attributess + + Checks if node has attributes + + + + Description + + boolDomNode->has_attributes + + + + This function checks if the node has attributes. + + + See also DomNode_has_child_nodes. + + + + + + + + + + + DomAttribute->name + + Returns name of attribute + + + + Description + + boolDomAttribute->name + + + + This function returns the name of the attribute. + + + See also DomAttribute_value. + + + + + + + DomAttribute->value + + Returns value of attribute + + + + Description + + boolDomAttribute->value + + + + This function returns the value of the attribute. + + + See also DomAttribute_name. + + + + + + + DomAttribute->specified + + Checks if attribute is specified + + + + Description + + boolDomAttribute->specified + + + + Check DOM standard for a detailed explanation. + + + + + + + + + + + DomDocumentType->name + + Returns name of document type + + + + Description + + stringDomDocumentType->name + + + + This function returns the name of the document type. + + + + + + + DomDocumentType->entities + + Returns list of entities + + + + Description + + arrayDomDocumentType->entities + + + + &warn.undocumented.func; + + + + + + + DomDocumentType->notations + + Returns list of notations + + + + Description + + arrayDomDocumentType->notations + + + + &warn.undocumented.func; + + + + + + + DomDocumentType->public_id + + Returns public id of document type + + + + Description + + stringDomDocumentType->public_id + + + + This function returns the public id of the document type. + + + The following example echos nothing. + + Retrieving the public id + +doctype(); +echo $doctype->public_id(); +?> +]]> + + + + + + + + + DomDocumentType->system_id + + Returns system id of document type + + + + Description + + stringDomDocumentType->system_id + + + + Returns the system id of the document type. + + + The following example echos + '/share/sgml/Norman_Walsh/db3xml10/db3xml10.dtd'. + + Retrieving the system id + +doctype(); +echo $doctype->system_id(); +?> +]]> + + + + + + + + + DomDocumentType->internal_subset + + Returns internal subset + + + + Description + + boolDomDocumentType->internal_subset + + + + &warn.undocumented.func; + + + + + + + + + domxml_node @@ -889,10 +2381,10 @@ $children = $head->children(); Description - - objectdomxml_node_unlink_node - - + + objectdomxml_node_unlink_node + + &warn.undocumented.func; @@ -930,10 +2422,10 @@ $children = $head->children(); Description - - stringdomxml_version - - + + stringdomxml_version + + This function returns the version of the XML library version currently used.