diff --git a/functions/domxml.xml b/functions/domxml.xml index f9ef9ec2ab..12ab610100 100644 --- a/functions/domxml.xml +++ b/functions/domxml.xml @@ -1,40 +1,146 @@ - + 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). + The domxml extension has been overhauled in PHP Version 4.3.0 in favour + of a better compliance of 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 xmltree to turn the + 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 dumpmem cannot be + 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, set_attribute, etc. and finally - dumpmem functions. + DomDocument_dump_mem functions. Requirements - These functions are only available if PHP was configured with + This extension is 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. + + + + + Deprecated functions + + + Deprecated functions and its replacements + + + + Old function + New function + + + + + xmldoc + domxml_open_mem + + + xmldocfiel + domxml_open_file + + + domxml_new_xmldoc + domxml_new_doc + + + domxml_dump_mem + DomDocument_dump_mem + + + domxml_dump_mem_file + DomDocument_dump_file + + + DomDocument_dump_mem_file + DomDocument_dump_file + + + DomDocument_add_root + DomDocument_create_element followed by + DomNode_append_child + + + DomDocument_dtd + DomDocument_doctype + + + DomDocument_root + DomDocument_document_element + + + DomDocument_children + DomNode_child_nodes + + + DomDocument_imported_node + No replacement. + + + DomNode_add_child + Create a new node with e.g. + DomDocument_create_element und add it with + DomNode_append_child. + + + + DomNode_children + DomNode_child_nodes + + + DomNode_parent + DomNode_parent_node + + + DomNode_new_child + Create a new node with e.g. + DomDocument_create_element und add it with + DomNode_append_child. + + + + DomNode_set_content + Create a new node with e.g. + DomDocument_create_text_node und add it with + DomNode_append_child. + + + + DomNode_get_content + Content is just a text node and can be accessed with + DomNode_child_nodes. + + + + DomNode_set_content + Content is just a text node and can be added with + DomNode_append_child. + + + + +
@@ -207,11 +313,11 @@ DomCData : DomNode - DomParser - + Parser + Currently still called DomParser - XPathContext> + XPathContext @@ -227,14 +333,14 @@ Method name Function name - Description + Remark doctype DomDocument_doctype - Returns the document type + document_elemnent @@ -287,34 +393,34 @@ - add_root - domxml_add_root - + dump_mem + DomDocument_dump_mem + not DOM standard - dtd - domxml_intdtd - + dump_file + DomDocument_dump_file + not DOM standard - dumpmem - domxml - + html_dump_mem + DomDocument_html_dump_mem + not DOM standard xpath_init xpath_init - + not DOM standard xpath_new_context xpath_new_context - + not DOM standard xptr_new_context xptr_new_context - + not DOM standard @@ -329,7 +435,7 @@ Method name Function name - Description + Remark @@ -385,7 +491,7 @@ Method name - Description + Remark @@ -446,27 +552,35 @@ - new_child - Not in DOM standard - - - get_attribute - Not in DOM standard - - - set_attribute - Not in DOM standard - - - DomNode_attributes + DomNode_clone_node - node + DomNode_attributes + + + + DomNode_unlink_node Not in DOM standard - set_content + 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 @@ -482,7 +596,7 @@ Method name - Description + Remark @@ -514,7 +628,7 @@ Method name Function name - Description + Remark @@ -535,24 +649,24 @@ - DomParser class + Parser class Method name Function name - Description + Remark add_chunk - DomParser_add_chunk + Parser_add_chunk end - DomParser_end + Parser_end @@ -568,7 +682,7 @@ Method name Function name - Description + Remark @@ -600,7 +714,7 @@ Method name Function name - Description + Remark @@ -651,7 +765,10 @@ 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. + following example section. You could also create an xml document + read it with DomDocument_open_file. + + Include file example.inc with xml string @@ -686,66 +803,128 @@ morerows='1'>b1c1 - + - xmldoc + domxml_open_mem Creates a DOM object of an XML document Description - - objectxmldoc - stringstr - - &warn.experimental.func; + + objectdomxml_open_mem + stringstr + The function parses the XML document in str and returns an object of class "Dom - document", having the properties as listed above. + document", having the properties as listed above. This function, + domxml_open_file or domxml_new_doc + must be called before any other function calls. + + + + Opening a xml document in a string + +document_element(); +?> +]]> + + + + + See also domxml_open_file, + domxml_new_doc. - - See also xmldocfile - - + - xmldocfile + domxml_open_file Creates a DOM object from XML file Description - - objectxmldocfile - stringfilename - - &warn.experimental.func; + + objectdomxml_open_file + stringfilename + The function parses the XML document in the file named filename and returns an object of class "Dom document", having the properties as listed above. The file is accessed read-only. - - See also xmldoc - + + + Opening a xml document from a file + +document_element(); +?> +]]> + + + + + See also domxml_open_mem, + domxml_new_doc. + - + - xmltree + domxml_new_doc + + Creates new empty XML document + + + + Description + + objectdomxml_new_doc + stringversion + + &warn.experimental.func; + + Creates a new dom document from scratch and returns it. + + + See also DomDocument_add_root + + + + + + + domxml_xmltree Creates a tree of PHP objects from an XML document Description - - objectxmltree - stringstr - + + objectdomxml_xmltree + stringstr + &warn.experimental.func; The function parses the XML document in @@ -760,6 +939,25 @@ morerows='1'>b1c1 + + + domxml_version + + Get XML library version + + + + Description + + stringdomxml_version + + + + This function returns the version of the XML library version currently used. + + + + @@ -813,7 +1011,7 @@ morerows='1'>b1c1 - See also domxml_add_root + See also DomDocument_add_root @@ -1112,31 +1310,30 @@ print_r($root); - See also domxml_add_root + See also DomDocument_add_root - + - domxml_add_root + DomDocument->add_root [deprecated] - Adds a further root node + Adds a root node Description - resourcedomxml_add_root - resourcedoc + resourceDomDocument->add_root stringname &warn.experimental.func; Adds a root element node to a dom document and returns the new node. - The element name is given in the second parameter. + The element name is given in the passed parameter. @@ -1144,11 +1341,11 @@ print_r($root); add_root("HTML"); $head = $root->new_child("HEAD", ""); $head->new_child("TITLE", "Hier der Titel"); -echo $doc->dumpmem(); +echo htmlentities($doc->dump_mem()); ?> ]]> @@ -1157,9 +1354,9 @@ echo $doc->dumpmem(); - + - domxml_dumpmem + DomDocument->dump_mem Dumps the internal XML tree back into a string @@ -1167,241 +1364,147 @@ echo $doc->dumpmem(); Description - stringdomxml_dumpmem - resourcedoc + stringDomDocument->dump_mem boolformat &warn.experimental.func; Creates an XML document from the dom representation. This function - usually is called after a building a new dom document from scratch - as in the example of domxml_add_root. The - format specifies whether the output should be neatly - formatted, or not. + usually is called after building a new dom document from scratch + as in the example below. The + format specifies whether the output should be + neatly formatted, or not. + + + + Creating a simple HTML document header + +create_element("HTML"); +$root = $doc->append_child($root); +$head = $doc->create_element("HEAD"); +$head = $root->append_child($head); +$title = $doc->create_element("TITLE"); +$title = $head->append_child($title); +$text = $doc->create_text_node("This is the title"); +$text = $title->append_child($text); +echo "
";
+echo htmlentities($doc->dump_mem(true));
+echo "
"; +?> +]]> + + - The second parameter was added in PHP 4.3.0. + The first parameter was added in PHP 4.3.0. - See also domxml_add_root + See also DomDocument_dump_file, + DomDocument_html_dump_mem. - + - domxml_attributes + DomDocument->dump_file - Returns an array of attributes of a node + Dumps the internal XML tree back into a file Description - - arraydomxml_attributes - resourcenode - - &warn.experimental.func; + + stringDomDocument->dump_file + stringfilename + boolcompressionmode + boolformat + - Returns all attributes of a node as array of objects of type - "dom attribute". - - - - - - - domxml_get_attribute - - Returns a certain attribute of a node - - - - Description - - objectdomxml_get_attribute - resourcenode - stringname - - &warn.experimental.func; - - Returns the attribute with name name of the given - node. - - - See also domxml_set_attribute - - - - - - - domxml_set_attribute - - - - - Description - - objectdomxml_set_attribute - resourcenode - stringname - stringvalue - - &warn.experimental.func; - - Sets an attribute with name name of the given - node on a value. + Creates an XML document from the dom representation. This function + usually is called after building a new dom document from scratch + as in the example below. The + format specifies whether the output should be + neatly formatted, or not. The first parameter specifies the name of the + filename and the second parameter, whether it should be compressed or not. - If we take the example from domxml_add_root it - is simple to add an attribute to the HEAD element by the simply calling - the set_attribute function of the node class. - Adding an attribute to an element + Creating a simple HTML document header add_root("HTML"); -$head = $root->new_child("HEAD", ""); -$head->new_child("TITLE", "Hier der Titel"); -$head->set_attribute("Language", "ge"); -echo $doc->dumpmem(); +$doc = domxml_new_doc("1.0"); +$root = $doc->create_element("HTML"); +$root = $doc->append_child($root); +$head = $doc->create_element("HEAD"); +$head = $root->append_child($head); +$title = $doc->create_element("TITLE"); +$title = $head->append_child($title); +$text = $doc->create_text_node("This is the title"); +$text = $title->append_child($text); +$doc->dump_file("/tmp/test.xml", false, true); ?> ]]> + + See also DomDocument_dump_mem + DomDocument_html_dump_mem. + - + - domxml_children + DomDocument->html_dump_mem - Returns children of a node or document + Dumps the internal XML tree back into a string as HTML Description - - arraydomxml_children - objectdoc|node - - &warn.experimental.func; + + stringDomDocument->html_dump_mem + + - Returns all children of a node as an array of nodes. + Creates an HTML document from the dom representation. This function + usually is called after building a new dom document from scratch + as in the example below. - In the following example the variable children will - contain an array with one node of type XML_ELEMENT. This node is - the TITLE element. - Adding an attribute to an element + Creating a simple HTML document header add_root("HTML"); -$head = $root->new_child("HEAD", ""); -$head->new_child("TITLE", "Hier der Titel"); -$head->set_attribute("Language", "ge"); -$children = $head->children(); +$doc = domxml_new_doc("1.0"); +$root = $doc->create_element("HTML"); +$root = $doc->append_child($root); +$head = $doc->create_element("HEAD"); +$head = $root->append_child($head); +$title = $doc->create_element("TITLE"); +$title = $head->append_child($title); +$text = $doc->create_text_node("This is the title"); +$text = $title->append_child($text); +echo "
";
+echo htmlentities($doc->html_dump_mem());
+echo "
"; ?> ]]> - - - - - - domxml_new_child - - Adds new child node - - - - Description - - resourcedomxml_new_child - stringname - stringcontent - - &warn.experimental.func; - Adds a new child of type element to a node and returns it. - - - - - - - domxml_new_xmldoc - - Creates new empty XML document - - - - Description - - objectdomxml_new_xmldoc - stringversion - - &warn.experimental.func; - - Creates a new dom document from scratch and returns it. - - - See also domxml_add_root - - - - - - - xpath_new_context - - Creates new xpath context - - - - Description - - objectxpath_new_context - objectdom document - - &warn.experimental.func; - - - - See also xpath_eval - - - - - - - xpath_eval - - Evaluates the XPath Location Path in the given string - - - - Description - - arrayxpath_eval - objectxpath context - - &warn.experimental.func; - - - - See also xpath_new_context + See also DomDocument_dump_file, + DomDocument_html_dump_mem. @@ -1441,7 +1544,11 @@ $children = $head->children(); stringname - &warn.undocumented.func; + Returns the attribute with name name of the + current node. + + + See also DomElement_set_attribute @@ -1461,7 +1568,26 @@ $children = $head->children(); stringvalue - &warn.undocumented.func; + Sets an attribute with name name ot the given + value. If the attribute does not exist, it will be created. + + + + Setting an attribute + +create_element("para"); +$newnode = $doc->append_child($node); +$newnode->set_attribute("align", "left"); +?> +]]> + + + + + See also DomElement_get_attribute @@ -1928,7 +2054,7 @@ while($child) { create_element("para"); $node = $doc->append_child($node); $children = $doc->children(); @@ -1968,7 +2094,7 @@ print_r($children); create_element("para"); $node = $doc->append_child($node); $children = $doc->children(); @@ -2004,11 +2130,39 @@ print_r($children); 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 + before the node refnode. The return value is the + inserted node. If you plan to do further modifications on the appended child you must use the returned node. + + DomNode_insert_before is very similar to + DomNode_append_child as the following example shows + which does the same as the example at + DomNode_append_child. + + + + Adding a child + +get_elements_by_tagname("informaltable"); +print_r($elements); +$element = $elements[0]; + +$newnode = $element->insert_before($element, $element); +$children = $newnode->children(); +$attr = $children[1]->set_attribute("align", "left"); + +echo "
";
+$xmlfile = $dom->dump_mem();
+echo htmlentities($xmlfile);
+echo "
"; +]]> + + + See also DomNode_append_child. @@ -2030,26 +2184,79 @@ print_r($children); This functions appends a child to an existing list of children or creates - a new child. The child can be created with e.g. + a new list of children. The child can be created with e.g. DomDocument_create_element, - DomDocument_create_text etc. The return value is the + DomDocument_create_text etc. or simply by using any + other node. + + + Before a new child is appended it is first duplicated. Therefore the new + child is a completely new copy which can be modified without changing the + node which was passed to this function. If the node passed has children + itself, they will be duplicated as well, which makes it quite easy to + duplicate large parts of a xml document. The return value is the appended child. If you plan to do further modifications on the appended child you must use the returned node. + The following example will add a new element node to a fresh document + and sets the attribute "align" to "left". Adding a child create_element("para"); -$node = $doc->append_child($node); -$node->set_attribute("align", "left"); +$newnode = $doc->append_child($node); +$newnode->set_attribute("align", "left"); ?> ]]> + The above example could also be written as the following: + + Adding a child + +create_element("para"); +$node->set_attribute("align", "left"); +$newnode = $doc->append_child($node); +?> +]]> + + + A more comples example is the one below. It first searches for a certain + element, duplicates it including its children and adds it as a sibling. + Finally a new attribute is added to one of the children of the new + sibling and the whole document is dumped. + + Adding a child + +get_elements_by_tagname("informaltable"); +print_r($elements); +$element = $elements[0]; + +$parent = $element->parent_node(); +$newnode = $parent->append_child($element); +$children = $newnode->children(); +$attr = $children[1]->set_attribute("align", "left"); + +echo "
";
+$xmlfile = $dom->dump_mem();
+echo htmlentities($xmlfile);
+echo "
"; +]]> + + + The above example could also be done with + DomNode_insert_before instead of + DomNode_append_child. See also DomNode_insert_before. @@ -2101,6 +2308,183 @@ $node->set_attribute("align", "left"); + + + DomNode->prefix + + Returns name space prefix of node + + + + Description + + stringDomNode->prefix + + + + Returns the name space prefix of the node. + + + + + + + DomNode->clone_node + + Clones a node + + + + Description + + objectDomNode->clone_node + + + + &warn.undocumented.func; + + + + + + + DomNode->unlink_node + + Deletes node + + + + Description + + objectDomNode->unlink_node + + + + &warn.undocumented.func; + + + + + + + DomNode->replace_node + + Replaces node + + + + Description + + objectDomNode->replace_node + + + + &warn.undocumented.func; + + + + + + + DomNode->set_content + + Sets content of node + + + + Description + + boolDomNode->set_content + + + + &warn.undocumented.func; + + + + + + + DomNode->get_content + + Gets content of node + + + + Description + + stringDomNode->get_content + + + + &warn.undocumented.func; + + + + + + + DomNode->dump_node + + Dumps a single node + + + + Description + + stringDomNode->dump_node + + + + &warn.undocumented.func; + + + See also DomDocument_dump_mem. + + + + + + + DomNode->set_name + + Sets name of node + + + + Description + + boolDomNode->set_name + + + + Sets name of node. + + + See also DomNode_node_name. + + + + + + + DomNode->is_blank_node + + Checks if node is blank + + + + Description + + boolDomNode->is_blank_node + + + + &warn.undocumented.func; + + + + @@ -2254,7 +2638,7 @@ $node->set_attribute("align", "left"); public_id(); system_id(); - - + - + - domxml_node + DomProcessingInstruction->target - Creates node - - - - Description - - objectdomxml_node - stringname - - - &warn.undocumented.func; - - - - - - - domxml_node_set_content - - Sets content of a node - - - - Description - - booldomxml_node_set_content - stringcontent - - - &warn.undocumented.func; - - - - - - - domxml_node_unlink_node - - Deletes node + Returns target of pi node Description - objectdomxml_node_unlink_node + stringDomProcessingInstruction->target @@ -2391,6 +2736,74 @@ echo $doctype->system_id(); + + + DomProcessingInstruction->data + + Returns data of pi node + + + + Description + + stringDomProcessingInstruction->data + + + + &warn.undocumented.func; + + + + + + + + + + + + xpath_new_context + + Creates new xpath context + + + + Description + + objectxpath_new_context + objectdom document + + &warn.experimental.func; + + + + See also xpath_eval + + + + + + + xpath_eval + + Evaluates the XPath Location Path in the given string + + + + Description + + arrayxpath_eval + objectxpath context + + &warn.experimental.func; + + + + See also xpath_new_context + + + + xpath_eval_expression @@ -2413,25 +2826,6 @@ echo $doctype->system_id(); - - - domxml_version - - Get XML library version - - - - Description - - stringdomxml_version - - - - This function returns the version of the XML library version currently used. - - - - xptr_new_context