php-doc-en/functions/domxml.xml

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

  <partintro>
   &warn.experimental;
   <simpara>
    This documentation is not finished yet. Don't start to translate it
    or use it as a programming reference (steinm@php.net).
   </simpara>
   <simpara>
    These functions are only available if PHP was configured with
    <option role="configure">--with-dom=[DIR]</option>, using the
    <ulink url="&url.domxml;">GNOME xml library</ulink>.
    You will need at least libxml-2.2.7
    These functions have been added in PHP 4.
   </simpara>
   <simpara>
    The extension allows you to operate on an XML document with the DOM API.
    It also provides a function <function>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>dumpmem</function> cannot be
    applied to it. Therefore, if you want to read an XML file and write
    a modified version use the <function>add_node</function>,
    <function>set_attribute</function>, etc. and finally
    <function>dumpmem</function> functions.
   </simpara>
   <simpara>
    This module defines the following constants:
   </simpara>
   <table>
    <title>XML constants</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Constant</entry>
       <entry>Value</entry>
       <entry>Description</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>XML_ELEMENT_NODE</entry>
       <entry>1</entry>
       <entry>Node is an element</entry>
      </row>
      <row>
       <entry>XML_ATTRIBUTE_NODE</entry>
       <entry>2</entry>
       <entry>Node is an attribute</entry>
      </row>
      <row>
       <entry>XML_TEXT_NODE</entry>
       <entry>3</entry>
       <entry>Node is a piece of text</entry>
      </row>
      <row>
       <entry>XML_CDATA_SECTION_NODE</entry>
       <entry>4</entry>
       <entry></entry>
      </row>
      <row>
       <entry>XML_ENTITY_REF_NODE</entry>
       <entry>5</entry>
       <entry></entry>
      </row>
      <row>
       <entry>XML_ENTITY_NODE</entry>
       <entry>6</entry>
       <entry>Node is an entity like &amp;nbsp;</entry>
      </row>
      <row>
       <entry>XML_PI_NODE</entry>
       <entry>7</entry>
       <entry>Node is a processing instruction</entry>
      </row>
      <row>
       <entry>XML_COMMENT_NODE</entry>
       <entry>8</entry>
       <entry>Node is a comment</entry>
      </row>
      <row>
       <entry>XML_DOCUMENT_NODE</entry>
       <entry>9</entry>
       <entry>Node is a document</entry>
      </row>
      <row>
       <entry>XML_DOCUMENT_TYPE_NODE</entry>
       <entry>10</entry>
       <entry></entry>
      </row>
      <row>
       <entry>XML_DOCUMENT_FRAG_NODE</entry>
       <entry>11</entry>
       <entry></entry>
      </row>
      <row>
       <entry>XML_NOTATION_NODE</entry>
       <entry>12</entry>
       <entry></entry>
      </row>
      <row>
       <entry>XML_GLOBAL_NAMESPACE</entry>
       <entry>1</entry>
       <entry></entry>
      </row>
      <row>
       <entry>XML_LOCAL_NAMESPACE</entry>
       <entry>2</entry>
       <entry></entry>
      </row>
     </tbody>
    </tgroup>
   </table>
   <simpara>
    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_".
   </simpara>
   <simpara>
    This module defines a number of classes, which are listed &mdash;
    including their
    properties and method &mdash; in the following table.
   </simpara>
   <para>
   <table>
    <title>DomDocument class (methods)</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Method name</entry>
       <entry>Function name</entry>
       <entry>Description</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>root</entry>
       <entry><function>domxml_root</function></entry>
       <entry></entry>
      </row>
      <row>
       <entry>children</entry>
       <entry><function>domxml_children</function></entry>
       <entry></entry>
      </row>
      <row>
       <entry>add_root</entry>
       <entry><function>domxml_add_root</function></entry>
       <entry></entry>
      </row>
      <row>
       <entry>dtd</entry>
       <entry><function>domxml_intdtd</function></entry>
       <entry></entry>
      </row>
      <row>
       <entry>dumpmem</entry>
       <entry><function>domxml</function></entry>
       <entry></entry>
      </row>
      <row>
       <entry>xpath_init</entry>
       <entry>xpath_init</entry>
       <entry></entry>
      </row>
      <row>
       <entry>xpath_new_context</entry>
       <entry>xpath_new_context</entry>
       <entry></entry>
      </row>
      <row>
       <entry>xptr_new_context</entry>
       <entry>xptr_new_context</entry>
       <entry></entry>
      </row>
     </tbody>
    </tgroup>
   </table>
   </para>

   <para>
   <table>
    <title>DomDocument class (attributes)</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Name</entry>
       <entry>Type</entry>
       <entry>Description</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>doc</entry>
       <entry>class DomDocument</entry>
       <entry>The object itself</entry>
      </row>
      <row>
       <entry>name</entry>
       <entry>string</entry>
       <entry></entry>
      </row>
      <row>
       <entry>url</entry>
       <entry>string</entry>
       <entry></entry>
      </row>
      <row>
       <entry>version</entry>
       <entry>string</entry>
       <entry>Version of XML</entry>
      </row>
      <row>
       <entry>encoding</entry>
       <entry>string</entry>
       <entry></entry>
      </row>
      <row>
       <entry>standalone</entry>
       <entry>long</entry>
       <entry>1 if the file is a standalone version</entry>
      </row>
      <row>
       <entry>type</entry>
       <entry>long</entry>
       <entry>One of the constants in table ... </entry>
      </row>
      <row>
       <entry>compression</entry>
       <entry>long</entry>
       <entry>1 if the file is compressed</entry>
      </row>
      <row>
       <entry>charset</entry>
       <entry>long</entry>
       <entry></entry>
      </row>
     </tbody>
    </tgroup>
   </table>
   </para>

   <para>
   <table>
    <title>DomNode class (methods)</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Name</entry>
       <entry>PHP name</entry>
       <entry>Description</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>lastchild</entry>
       <entry><function>domxml_last_child</function></entry>
       <entry></entry>
      </row>
      <row>
       <entry>children</entry>
       <entry><function>domxml_children</function></entry>
       <entry></entry>
      </row>
      <row>
       <entry>parent</entry>
       <entry><function>domxml_parent</function></entry>
       <entry></entry>
      </row>
      <row>
       <entry>new_child</entry>
       <entry><function>domxml_new_child</function></entry>
       <entry></entry>
      </row>
      <row>
       <entry>get_attribute</entry>
       <entry><function>domxml_get_attribute</function></entry>
       <entry></entry>
      </row>
      <row>
       <entry>set_attribute</entry>
       <entry><function>domxml_set_attribute</function></entry>
       <entry></entry>
      </row>
      <row>
       <entry>attributes</entry>
       <entry><function>domxml_attributes</function></entry>
       <entry></entry>
      </row>
      <row>
       <entry>node</entry>
       <entry><function>domxml_node</function></entry>
       <entry></entry>
      </row>
      <row>
       <entry><function>set_content</function></entry>
       <entry>domxml_set_content</entry>
       <entry></entry>
      </row>
     </tbody>
    </tgroup>
   </table>
   </para>

   <para>
   <table>
    <title>DomNode class (attributes)</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Name</entry>
       <entry>Type</entry>
       <entry>Description</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>node</entry>
       <entry>class DomNode</entry>
       <entry>The object itself</entry>
      </row>
      <row>
       <entry>type</entry>
       <entry>long</entry>
       <entry></entry>
      </row>
      <row>
       <entry>name</entry>
       <entry>string</entry>
       <entry></entry>
      </row>
      <row>
       <entry>content</entry>
       <entry>string</entry>
       <entry></entry>
      </row>
     </tbody>
    </tgroup>
   </table>
   </para>

  </partintro>

  <!-- class Dom document -->
  <!-- has member functions
        array root([int doc_handle]) 
           returns array of root nodes of this document. Array
           elements are objects of class "Dom node" having properties of
           "node" (resource), "type" (long), "name" (string)
           and optionally "content" (string).

        array children([ int node ])
           returns an array of child nodes of this element. Array
           elements are objects of class "Dom node" having properties
           of "node" (resource), "type" (long), "name" (string)
           and optionally "content" (string).

        object add_root([int doc_handle,] string name)
           Add a root node to document.

           returns an object of class "Dom node" having properties
           of "node" (resource), "type" (long), "name" (string)
           and optionally "content" (string). 

        object intdtd([int doc_handle])
           returns the DTD of document.

           returns an object of class "Dtd" having properties
           of "dtd" (resource), "sysid" (string), "name" (string)
           and optionally "extid" (string).

        string dumpmem([int doc_handle])
           dumps document into string.
    -->

   <!-- class Dom node
        object lastchild([int node])
          returns Dom node object

        array children([int node])
          as above

        object parent([ int node])
          returns Dom node object
          (parent of this node)

        new_child
        string getattr([int node,] string attrname)
          get value of attribute named attrname

        bool setattr([int node,] string attrname, string value)
          set value of given attribute.

        array attributes([int node])
          returns associative array of (string name, string value)
          pairs.

        object node(string name)
          creates a named Dom node object.
    -->

  <!-- class Dom Attribute
       name
    -->

  <!-- class Dom Namespace
    -->

  <!-- class Dtd
    -->        

  <refentry id="function.xmldoc">
   <refnamediv>
    <refname>xmldoc</refname>
    <refpurpose>Creates a DOM object of an XML document</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>object <function>xmldoc</function></funcdef>
      <paramdef>string <parameter>str</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    &warn.experimental.func;
    <para>
     The function parses the XML document in
     <parameter>str</parameter> and returns an object of class "Dom
     document", having the properties as listed above.
    </para>
    <simpara>
     See also <function>xmldocfile</function>
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.xmldocfile">
   <refnamediv>
    <refname>xmldocfile</refname>
    <refpurpose>Creates a DOM object from XML file</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>object <function>xmldocfile</function></funcdef>
      <paramdef>string <parameter>filename</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    &warn.experimental.func;
    <para>
     The function parses the XML document in the file named
     <parameter>filename</parameter> and returns an object of class
     "Dom document", having the properties as listed above.
     The file is accessed read-only.
    </para>
    <simpara>
     See also <function>xmldoc</function>
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.xmltree">
   <refnamediv>
    <refname>xmltree</refname>
    <refpurpose>
     Creates a tree of PHP objects from XML document
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>object <function>xmltree</function></funcdef>
      <paramdef>string <parameter>str</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    &warn.experimental.func;
    <para>
     The function parses the XML document in
     <parameter>str</parameter> and returns a tree PHP objects as the
     parsed document. This function is isolated from the other functions,
     which means you cannot access the tree with any of the other functions.
     Modifying it, for example by adding nodes, makes no sense since there
     is currently no way to dump it as an XML file.
     However this function may be valuable if you want to read a file and
     investigate the content.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.domxml-root">
   <refnamediv>
    <refname>domxml_root</refname>
    <refpurpose>
     Returns root element node
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>object <function>domxml_root</function></funcdef>
      <paramdef>object <parameter>doc</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    &warn.experimental.func;
    <para>
     <function>domxml_root</function> 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.
    </para>
    <para>
     The following example returns just the element with name CHAPTER and
     prints it. The other root node -- the comment -- is not returned.
     <example>
      <title>Retrieving root element</title>
      <programlisting role="php">
&lt;?php
$xmlstr = "&lt;?xml version='1.0' standalone='yes'?&gt;
&lt;!DOCTYPE chapter SYSTEM '/share/sgml/Norman_Walsh/db3xml10/db3xml10.dtd'
[ &lt;!ENTITY sp \"spanish\">
]>
&lt;!-- lsfj  --&gt;
&lt;chapter language='en'>&lt;title language='en'>Title&lt;/title>
 &lt;para language='ge'>
  &amp;sp;
  &lt;!-- comment --&gt;
  &lt;informaltable language='&amp;sp;'>
   &lt;tgroup cols='3'>
    &lt;tbody>
     &lt;row>&lt;entry>a1&lt;/entry>&lt;entry
morerows='1'>b1&lt;/entry>&lt;entry>c1&lt;/entry>&lt;/row>
&lt;row>&lt;entry>a2&lt;/entry>&lt;entry>c2&lt;/entry>&lt;/row>
     &lt;row>&lt;entry>a3&lt;/entry>&lt;entry>b3&lt;/entry>&lt;entry>c3&lt;/entry>&lt;/row>
    &lt;/tbody>
   &lt;/tgroup>
  &lt;/informaltable>
 &lt;/para>
&lt;/chapter>";

if(!$dom = xmldoc($xmlstr)) {
  echo "Error while parsing the document\n";
  exit;
}

$root = $dom-&gt;root();
/* or $root = domxml_root($dom); */
print_r($root);
?&gt;
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.domxml-add-root">
   <refnamediv>
    <refname>domxml_add_root</refname>
    <refpurpose>
     Adds a further root node
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>resource <function>domxml_add_root</function></funcdef>
      <paramdef>resource <parameter>doc</parameter></paramdef>
      <paramdef>string <parameter>name</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    &warn.experimental.func;
    <para>
     Adds a root element node to a dom document and returns the new node.
     The element name is given in the second parameter.
    </para>
    <para>
     <example>
      <title>Creating a simple HTML document header</title>
      <programlisting role="php">
&lt;?php
$doc = new_xmldoc("1.0");
$root = $doc-&gt;add_root("HTML");
$head = $root-&gt;new_child("HEAD", "");
$head-&gt;new_child("TITLE", "Hier der Titel");
echo $doc-&gt;dumpmem();
?&gt;
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.domxml-dumpmem">
   <refnamediv>
    <refname>domxml_dumpmem</refname>
    <refpurpose>
     Dumps the internal XML tree back into a string
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>string <function>domxml_dumpmem</function></funcdef>
      <paramdef>resource <parameter>doc</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    &warn.experimental.func;
    <para>
     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 <function>domxml_add_root</function>.
    </para>
    <para>
     See also <function>domxml_add_root</function>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.domxml-attributes">
   <refnamediv>
    <refname>domxml_attributes</refname>
    <refpurpose>
     Returns an array of attributes of a node
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>array <function>domxml_attributes</function></funcdef>
      <paramdef>resource <parameter>node</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    &warn.experimental.func;
    <para>
     Returns all attributes of a node as array of objects of type
     "dom attribute".
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.domxml-get-attribute">
   <refnamediv>
    <refname>domxml_get_attribute</refname>
    <refpurpose>
     Returns a certain attribute of a node
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>object <function>domxml_get_attribute</function></funcdef>
      <paramdef>resource <parameter>node</parameter></paramdef>
      <paramdef>string <parameter>name</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    &warn.experimental.func;
    <para>
     Returns the attribute with name <parameter>name</parameter> of the given
     node.
    </para>
    <simpara>
     See also <function>domxml_set_attribute</function>
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.domxml-set-attribute">
   <refnamediv>
    <refname>domxml_set_attribute</refname>
    <refpurpose>
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>object <function>domxml_set_attribute</function></funcdef>
      <paramdef>resource <parameter>node</parameter></paramdef>
      <paramdef>string <parameter>name</parameter></paramdef>
      <paramdef>string <parameter>value</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    &warn.experimental.func;
    <para>
     Sets an attribute with name <parameter>name</parameter> of the given
     node on a value.
    </para>
    <para>
     If we take the example from <function>domxml_add_root</function> it
     is simple to add an attribute to the HEAD element by the simply calling
     the <function>set_attribute</function> function of the node class.
     <example>
      <title>Adding an attribute to an element</title>
      <programlisting role="php">
&lt;?php
$doc = new_xmldoc("1.0");
$root = $doc-&gt;add_root("HTML");
$head = $root-&gt;new_child("HEAD", "");
$head-&gt;new_child("TITLE", "Hier der Titel");
$head-&gt;set_attribute("Language", "ge");
echo $doc-&gt;dumpmem();
?&gt;
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.domxml-children">
   <refnamediv>
    <refname>domxml_children</refname>
    <refpurpose>
     Returns children of a node or document
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>array <function>domxml_children</function></funcdef>
      <paramdef>object <parameter>doc|node</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    &warn.experimental.func;
    <para>
     Returns all children of a node as an array of nodes.
    </para>
    <para>
     In the following example the variable <varname>children</varname> will
     contain an array with one node of type XML_ELEMENT. This node is
     the TITLE element.
     <example>
      <title>Adding an attribute to an element</title>
      <programlisting role="php">
&lt;?php
$doc = new_xmldoc("1.0");
$root = $doc-&gt;add_root("HTML");
$head = $root-&gt;new_child("HEAD", "");
$head-&gt;new_child("TITLE", "Hier der Titel");
$head-&gt;set_attribute("Language", "ge");
$children = $head-&gt;children();
?&gt;
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.domxml-new-child">
   <refnamediv>
    <refname>domxml_new_child</refname>
    <refpurpose>
     Adds new child node
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>resource <function>domxml_new_child</function></funcdef>
      <paramdef>string <parameter>name</parameter></paramdef>
      <paramdef>string <parameter>content</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    &warn.experimental.func;
    <para>
     Adds a new child of type element to a node and returns it.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.domxml-new-xmldoc">
   <refnamediv>
    <refname>domxml_new_xmldoc</refname>
    <refpurpose>
     Creates new empty XML document
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>object <function>domxml_new_xmldoc</function></funcdef>
      <paramdef>string <parameter>version</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    &warn.experimental.func;
    <para>
     Creates a new dom document from scratch and returns it.
    </para>
    <para>
     See also <function>domxml_add_root</function>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.xpath-new-context">
   <refnamediv>
    <refname>xpath_new_context</refname>
    <refpurpose>
     Creates new xpath context
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>object <function>xpath_new_context</function></funcdef>
      <paramdef>object <parameter>dom document</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    &warn.experimental.func;
    <para>
    </para>
    <para>
     See also <function></function>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.xpath-eval">
   <refnamediv>
    <refname>xpath_eval</refname>
    <refpurpose>
     Evaluates an xpath expression
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>array <function>xpath_eval</function></funcdef>
      <paramdef>object <parameter>xpath context</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    &warn.experimental.func;
    <para>
    </para>
    <para>
     See also <function></function>
    </para>
   </refsect1>
  </refentry>

 </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
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
-->