<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.22 $ -->
<!-- Purpose: xml -->
<!-- Membership: pecl, external -->

 <reference id="ref.domxml">
  <title>DOM XML Functions</title>
  <titleabbrev>DOM XML</titleabbrev>

  <partintro>
   <section id="domxml.intro">
    &reftitle.intro;
    <para>
     The DOM XML extension has been overhauled in PHP 4.3.0 to better comply with 
     the DOM standard. The extension still contains
     many old functions, but they should no longer be used. In particular, functions 
     that are not object-oriented 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 <function>DomDocument_create_element</function>,
     <function>DomDocument_create_text_node</function>,
     <function>set_attribute</function>, etc. and finally the
     <function>DomDocument_dump_mem</function> function.
    </para>
    <note>
     <para>
      &pecl.moved-ver;5.0.0.
     </para>
    </note>
    <note>
     <simpara>
      This extension is no longer marked experimental. It will, however, never
      be released with PHP 5, and will only be distributed with PHP 4. 
      If you need DOM XML support with PHP 5 you can use the
      <link linkend="ref.dom">DOM</link> extension. This
      <literal>domxml</literal> extension is not compatible with the
      <link linkend="ref.dom">DOM</link> extension.
     </simpara>
    </note>
   </section>

   <section id="domxml.requirements">
    &reftitle.required;
    <para>
     This extension makes use of the
     <ulink url="&url.libxml;">GNOME XML library</ulink>. Download
     and install this library. You will need at least libxml-2.4.14.
     To use DOM XSLT features you can use the
     <ulink url="&url.libxslt;">libxslt library</ulink> and EXSLT
     enhancements from <ulink url="&url.exslt;">&url.exslt;</ulink>.
     Download and install these libraries if you plan to use (enhanced) XSLT
     features. You will need at least libxslt-1.0.18.
    </para>
   </section>

   &reference.domxml.configure;

   <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 no longer be used. These functions are listed in the following table.
     The function <function>DomNode_append_child</function> has changed its
     behaviour. It now 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>xmldocfile</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> and 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> and 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> and 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 closely
     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 functions are mainly to retain compatibility
     to older versions of the extension, and should not be used when creating new
     scripts.
    </para>
    <para>
     This API differs from the official DOM API in two ways. First, all
     class attributes are implemented as functions with the same name.
     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 -
     including their
     method - 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_element</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 every example, it will be put into a file
     which will be included by each example. This include file is shown in the
     following example section. Alternatively, you could create an XML document and
     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'>
  &sp;
  <!-- comment -->
  <informaltable ID='findme' language='&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
-->