php-doc-en/reference/domxml/reference.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
 <reference id="ref.domxml">
  <title>DOM XML functions</title>
  <titleabbrev>DOM XML</titleabbrev>

  <partintro>
   <section id="domxml.intro">
    &reftitle.intro;
    &warn.experimental;
    <para>
     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.
    </para>
    <para>
     The extension allows you to operate on an XML document with the DOM API.
     It also provides a function <function>domxml_xmltree</function> 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 <function>DomDocument_dump_mem</function>
     cannot be
     applied to it. Therefore, if you want to read an XML file and write
     a modified version use the <function>DomDocument_create_element</function>,
     <function>DomDocument_create_text_node</function>,
     <function>set_attribute</function>, etc. and finally
     <function>DomDocument_dump_mem</function> functions.
    </para>
   </section>

   <section id="domxml.requirements">
    &reftitle.required;
    <para>
     This extension make use of the
     <ulink url="&url.domxml;">GNOME xml library</ulink>. Download
     and install this library. You will need at least libxml-2.2.7.
    </para>
   </section>

   <section id="domxml.installation">
    &reftitle.install;
    <para>
     This extension is only available if PHP was configured with
     <option role="configure">--with-dom=[DIR]</option>.
    </para>
   </section>

   <section id="domxml.deprecated">
    <title>Deprecated functions</title>
    <para>
     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 <function>DomNode_append_child</function> has changed its
     behaviour. It now actually adds a child and not a sibling. If this
     breaks your application use the non DOM function
     <function>DomNode_append_sibling</function>.
    </para>
    <para>
    <table>
     <title>Deprecated functions and their replacements</title>
     <tgroup cols="2">
      <thead>
       <row>
        <entry>Old function</entry>
        <entry>New function</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>xmldoc</entry>
        <entry><function>domxml_open_mem</function></entry>
       </row>
       <row>
        <entry>xmldocfiel</entry>
        <entry><function>domxml_open_file</function></entry>
       </row>
       <row>
        <entry>domxml_new_xmldoc</entry>
        <entry><function>domxml_new_doc</function></entry>
       </row>
       <row>
        <entry>domxml_dump_mem</entry>
        <entry><function>DomDocument_dump_mem</function></entry>
       </row>
       <row>
        <entry>domxml_dump_mem_file</entry>
        <entry><function>DomDocument_dump_file</function></entry>
       </row>
       <row>
        <entry>DomDocument_dump_mem_file</entry>
        <entry><function>DomDocument_dump_file</function></entry>
       </row>
       <row>
        <entry>DomDocument_add_root</entry>
        <entry><function>DomDocument_create_element</function> followed by
               <function>DomNode_append_child</function></entry>
       </row>
       <row>
        <entry>DomDocument_dtd</entry>
        <entry><function>DomDocument_doctype</function></entry>
       </row>
       <row>
        <entry>DomDocument_root</entry>
        <entry><function>DomDocument_document_element</function></entry>
       </row>
       <row>
        <entry>DomDocument_children</entry>
        <entry><function>DomNode_child_nodes</function></entry>
       </row>
       <row>
        <entry>DomDocument_imported_node</entry>
        <entry>No replacement.</entry>
       </row>
       <row>
        <entry>DomNode_add_child</entry>
        <entry>Create a new node with e.g.
         <function>DomDocument_create_element</function> und add it with
         <function>DomNode_append_child</function>.
        </entry>
       </row>
       <row>
        <entry>DomNode_children</entry>
        <entry><function>DomNode_child_nodes</function></entry>
       </row>
       <row>
        <entry>DomNode_parent</entry>
        <entry><function>DomNode_parent_node</function></entry>
       </row>
       <row>
        <entry>DomNode_new_child</entry>
        <entry>Create a new node with e.g.
         <function>DomDocument_create_element</function> und add it with
         <function>DomNode_append_child</function>.
        </entry>
       </row>
       <row>
        <entry>DomNode_set_content</entry>
        <entry>Create a new node with e.g.
         <function>DomDocument_create_text_node</function> und add it with
         <function>DomNode_append_child</function>.
        </entry>
       </row>
       <row>
        <entry>DomNode_get_content</entry>
        <entry>Content is just a text node and can be accessed with
         <function>DomNode_child_nodes</function>.
        </entry>
       </row>
       <row>
        <entry>DomNode_set_content</entry>
        <entry>Content is just a text node and can be added with
         <function>DomNode_append_child</function>.
        </entry>
       </row>
      </tbody>
     </tgroup>
    </table>
    </para>
   </section>

   &reference.domxml.constants;

   <section id="domxml.classes">
    <title>Classes</title>
    <para>
     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.
    </para>
    <para>
     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().
    </para>
    <para>
     This module defines a number of classes, which are listed &mdash;
     including their
     method &mdash; in the following tables. Classes with an equivalent in the
     DOM Standard are named DOMxxx.
    </para>
 
    <para>
    <table>
     <title>List of classes</title>
     <tgroup cols="2">
      <thead>
       <row>
        <entry>Class name</entry>
        <entry>Parent classes</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>DomAttribute</entry>
        <entry>DomNode</entry>
       </row>
       <row>
        <entry>DomCData</entry>
        <entry>DomNode</entry>
       </row>
       <row>
        <entry>DomComment</entry>
        <entry>DomCData : DomNode</entry>
       </row>
       <row>
        <entry>DomDocument</entry>
        <entry>DomNode</entry>
       </row>
       <row>
        <entry>DomDocumentType</entry>
        <entry>DomNode</entry>
       </row>
       <row>
        <entry>DomElement</entry>
        <entry>DomNode</entry>
       </row>
       <row>
        <entry>DomEntity</entry>
        <entry>DomNode</entry>
       </row>
       <row>
        <entry>DomEntityReference</entry>
        <entry>DomNode</entry>
       </row>
       <row>
        <entry>DomProcessingInstruction</entry>
        <entry>DomNode</entry>
       </row>
       <row>
        <entry>DomText</entry>
        <entry>DomCData : DomNode</entry>
       </row>
       <row>
        <entry>Parser</entry>
        <entry>Currently still called DomParser</entry>
       </row>
       <row>
        <entry>XPathContext</entry>
        <entry></entry>
       </row>
      </tbody>
     </tgroup>
    </table>
    </para>

    <para>
    <table>
     <title>DomDocument class (DomDocument : DomNode)</title>
     <tgroup cols="3">
      <thead>
       <row>
        <entry>Method name</entry>
        <entry>Function name</entry>
        <entry>Remark</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>doctype</entry>
        <entry><function>DomDocument_doctype</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>document_elemnent</entry>
        <entry><function>DomDocument_document_element</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>create_element</entry>
        <entry><function>DomDocument_create_element</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>create_text_node</entry>
        <entry><function>DomDocument_create_text_node</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>create_comment</entry>
        <entry><function>DomDocument_create_comment</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>create_cdata_section</entry>
        <entry><function>DomDocument_create_cdata_section</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>create_processing_instruction</entry>
        <entry><function>DomDocument_create_processing_instruction</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>create_attribute</entry>
        <entry><function>DomDocument_create_attribute</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>create_entity_reference</entry>
        <entry><function>DomDocument_create_entity_reference</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>get_elements_by_tagname</entry>
        <entry><function>DomDocument_get_elements_by_tagname</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>get_element_by_id</entry>
        <entry><function>DomDocument_get_element_by_id</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>dump_mem</entry>
        <entry><function>DomDocument_dump_mem</function></entry>
        <entry>not DOM standard</entry>
       </row>
       <row>
        <entry>dump_file</entry>
        <entry><function>DomDocument_dump_file</function></entry>
        <entry>not DOM standard</entry>
       </row>
       <row>
        <entry>html_dump_mem</entry>
        <entry><function>DomDocument_html_dump_mem</function></entry>
        <entry>not DOM standard</entry>
       </row>
       <row>
        <entry>xpath_init</entry>
        <entry>xpath_init</entry>
        <entry>not DOM standard</entry>
       </row>
       <row>
        <entry>xpath_new_context</entry>
        <entry>xpath_new_context</entry>
        <entry>not DOM standard</entry>
       </row>
       <row>
        <entry>xptr_new_context</entry>
        <entry>xptr_new_context</entry>
        <entry>not DOM standard</entry>
       </row>
      </tbody>
     </tgroup>
    </table>
    </para>

    <para>
    <table>
     <title>DomElement class (DomElement : DomNode)</title>
     <tgroup cols="3">
      <thead>
       <row>
        <entry>Method name</entry>
        <entry>Function name</entry>
        <entry>Remark</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>tagname</entry>
        <entry><function>DomElement_tagname</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>get_attribute</entry>
        <entry><function>DomElement_get_attribute</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>set_attribute</entry>
        <entry><function>DomElement_set_attribute</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>remove_attribute</entry>
        <entry><function>DomElement_remove_attribute</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>get_attribute_node</entry>
        <entry><function>DomElement_get_attribute_node</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>set_attribute_node</entry>
        <entry><function>DomElement_set_attribute_node</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>get_elements_by_tagname</entry>
        <entry><function>DomElement_get_elements_by_tagname</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>has_attribute</entry>
        <entry><function>DomElement_has_attribute</function></entry>
        <entry></entry>
       </row>
      </tbody>
     </tgroup>
    </table>
    </para>

    <para>
    <table>
     <title>DomNode class</title>
     <tgroup cols="2">
      <thead>
       <row>
        <entry>Method name</entry>
        <entry>Remark</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry><function>DomNode_node_name</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry><function>DomNode_node_value</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry><function>DomNode_node_type</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry><function>DomNode_last_child</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry><function>DomNode_first_child</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry><function>DomNode_child_nodes</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry><function>DomNode_previous_sibling</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry><function>DomNode_next_sibling</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry><function>DomNode_parent_node</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry><function>DomNode_owner_document</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry><function>DomNode_insert_before</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry><function>DomNode_append_child</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry><function>DomNode_append_sibling</function></entry>
        <entry>Not in DOM standard. This function emulates the former
         behaviour of <function>DomNode_append_child</function>.</entry>
       </row>
       <row>
        <entry><function>DomNode_remove_child</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry><function>DomNode_has_child_nodes</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry><function>DomNode_has_attributes</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry><function>DomNode_clone_node</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry><function>DomNode_attributes</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry><function>DomNode_unlink_node</function></entry>
        <entry>Not in DOM standard</entry>
       </row>
       <row>
        <entry><function>DomNode_replace_node</function></entry>
        <entry>Not in DOM standard</entry>
       </row>
       <row>
        <entry><function>DomNode_set_content</function></entry>
        <entry>Not in DOM standard, deprecated</entry>
       </row>
       <row>
        <entry><function>DomNode_get_content</function></entry>
        <entry>Not in DOM standard, deprecated</entry>
       </row>
       <row>
        <entry><function>DomNode_dump_node</function></entry>
        <entry>Not in DOM standard</entry>
       </row>
       <row>
        <entry><function>DomNode_is_blank_node</function></entry>
        <entry>Not in DOM standard</entry>
       </row>
      </tbody>
     </tgroup>
    </table>
    </para>

    <para>
    <table>
     <title>DomAttribute class (DomAttribute : DomNode)</title>
     <tgroup cols="3">
      <thead>
       <row>
        <entry>Method name</entry>
        <entry></entry>
        <entry>Remark</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>name</entry>
        <entry><function>DomAttribute_name</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>value</entry>
        <entry><function>DomAttribute_value</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>specified</entry>
        <entry><function>DomAttribute_specified</function></entry>
        <entry></entry>
       </row>
      </tbody>
     </tgroup>
    </table>
    </para>

    <para>
    <table>
     <title>DomProcessingInstruction class (DomProcessingInstruction : DomNode)</title>
     <tgroup cols="3">
      <thead>
       <row>
        <entry>Method name</entry>
        <entry>Function name</entry>
        <entry>Remark</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>target</entry>
        <entry><function>DomProcessingInstruction_target</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>data</entry>
        <entry><function>DomProcessingInstruction_data</function></entry>
        <entry></entry>
       </row>
      </tbody>
     </tgroup>
    </table>
    </para>

    <para>
    <table>
     <title>Parser class</title>
     <tgroup cols="3">
      <thead>
       <row>
        <entry>Method name</entry>
        <entry>Function name</entry>
        <entry>Remark</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>add_chunk</entry>
        <entry><function>Parser_add_chunk</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>end</entry>
        <entry><function>Parser_end</function></entry>
        <entry></entry>
       </row>
      </tbody>
     </tgroup>
    </table>
    </para>

    <para>
    <table>
     <title>XPathContext class</title>
     <tgroup cols="3">
      <thead>
       <row>
        <entry>Method name</entry>
        <entry>Function name</entry>
        <entry>Remark</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>eval</entry>
        <entry><function>XPathContext_eval</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>eval_expression</entry>
        <entry><function>XPathContext_eval_expression</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>register_ns</entry>
        <entry><function>XPathContext_register_ns</function></entry>
        <entry></entry>
       </row>
      </tbody>
     </tgroup>
    </table>
    </para>

    <para>
    <table>
      <title>DomDocumentType class (DomDocumentType : DomNode)</title>
     <tgroup cols="3">
      <thead>
       <row>
        <entry>Method name</entry>
        <entry>Function name</entry>
        <entry>Remark</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>name</entry>
        <entry><function>DomDocumentType_name</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>entities</entry>
        <entry><function>DomDocumentType_entities</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>notations</entry>
        <entry><function>DomDocumentType_notations</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>public_id</entry>
        <entry><function>DomDocumentType_public_id</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>system_id</entry>
        <entry><function>DomDocumentType_system_id</function></entry>
        <entry></entry>
       </row>
       <row>
        <entry>internal_subset</entry>
        <entry><function>DomDocumentType_internal_subset</function></entry>
        <entry></entry>
       </row>
      </tbody>
     </tgroup>
    </table>
    </para>

    <para>
     The classes DomDtd is derived from DomNode. DomComment is derived from
     DomCData
    </para>
   </section>

   <section id="domxml.examples">
    &reftitle.examples;
    <para>
     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 <function>DomDocument_open_file</function>.
    </para>
    <para>
     <example>
      <title>Include file example.inc with XML string</title>
      <programlisting role="php">
<![CDATA[
<?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>";
?>
]]>
      </programlisting>
     </example>
    </para>
   </section>
  </partintro>

&reference.domxml.functions;

 </reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->