Added SimpleXML->registerXPathNamespace, and added ns and prefix parameters to simplexml_load_file() and simplexml_load_string().

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@215197 c90b9560-bf6c-de11-be94-00142212c4b1

reference/simplexml/functions/simplexml-element-getDocNamespaces.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.6 $ -->
+<!-- $Revision: 1.7 $ -->
 <refentry id='function.simplexml-element-getDocNamespaces'>
  <refnamediv>
   <refname>SimpleXMLElement->getDocNamespaces()</refname>
@@ -107,6 +107,7 @@ var_dump($namespaces);
   <para>
    <simplelist>
     <member><xref linkend="function.simplexml-element-getNamespaces" /></member>
+    <member><xref linkend="function.simplexml-element-registerXPathNamespace" /></member>
    </simplelist>
   </para>
  </refsect1>

reference/simplexml/functions/simplexml-element-getNamespaces.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.6 $ -->
+<!-- $Revision: 1.7 $ -->
 <refentry id='function.simplexml-element-getNamespaces'>
  <refnamediv>
   <refname>SimpleXMLElement->getNamespaces()</refname>
@@ -89,6 +89,7 @@ array(1) {
   <para>
    <simplelist>
     <member><xref linkend="function.simplexml-element-getDocNamespaces" /></member>
+    <member><xref linkend="function.simplexml-element-registerXPathNamespace" /></member>
    </simplelist>
   </para>
  </refsect1>

reference/simplexml/functions/simplexml-element-registerXPathNamespace.xml

@@ -0,0 +1,142 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision: 1.1 $ -->
+<refentry id='function.simplexml-element-registerXPathNamespace'>
+ <refnamediv>
+  <refname>SimpleXMLElement->registerXPathNamespace()</refname>
+  <refpurpose>
+   Creates a prefix/ns context for the next XPath query
+  </refpurpose>
+ </refnamediv>
+ <refsect1 role="description">
+  &reftitle.description;
+  <classsynopsis>
+   <ooclass><classname>SimpleXMLElement</classname></ooclass>
+   <methodsynopsis>
+    <type>bool</type><methodname>registerXPathNamespace</methodname>
+    <methodparam><type>string</type><parameter>prefix</parameter></methodparam>
+    <methodparam><type>string</type><parameter>ns</parameter></methodparam>
+   </methodsynopsis>
+  </classsynopsis>
+  <para>
+   Creates a prefix/ns context for the next XPath query. In particular, this is
+   helpful if the provider of the given XML document alters the namespace
+   prefixes. <literal>registerXPathNamespace</literal> will create a prefix for
+   the associated namespace, allowing one to access nodes in that namespace 
+   without the need to change code to allow for the new prefixes dictated by the
+   provider.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>prefix</parameter></term>
+     <listitem>
+      <para>
+       The namespace prefix to use in the XPath query for the namespace given in 
+       <parameter>ns</parameter>.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>ns</parameter></term>
+     <listitem>
+      <para>
+       The namespace to use for the XPath query. This must match a namespace in
+       use by the XML document or the XPath query using 
+       <parameter>prefix</parameter> will not return any results.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>Setting a namespace prefix to use in an XPath query</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+$xml = <<<EOD
+<book xmlns:chap="http://example.org/chapter-title">
+    <title>My Book</title>
+    <chapter id="1">
+        <chap:title>Chapter 1</chap:title>
+        <para>Donec velit. Nullam eget tellus vitae tortor gravida scelerisque. 
+            In orci lorem, cursus imperdiet, ultricies non, hendrerit et, orci. 
+            Nulla facilisi. Nullam velit nisl, laoreet id, condimentum ut, 
+            ultricies id, mauris.</para>
+    </chapter>
+    <chapter id="2">
+        <chap:title>Chapter 2</chap:title>
+        <para>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Proin 
+            gravida. Phasellus tincidunt massa vel urna. Proin adipiscing quam 
+            vitae odio. Sed dictum. Ut tincidunt lorem ac lorem. Duis eros 
+            tellus, pharetra id, faucibus eu, dapibus dictum, odio.</para>
+    </chapter>
+</book>
+EOD;
+
+$sxe = new SimpleXMLElement($xml);
+
+$sxe->registerXPathNamespace('c', 'http://example.org/chapter-title');
+$result = $sxe->xpath('//c:title');
+
+foreach ($result as $title)
+{
+  echo $title . "\n";
+}
+
+?>
+]]>
+    </programlisting>
+    <para>
+     Notice how the XML document shown in the example sets a namespace with a 
+     prefix of <literal>chap</literal>. Imagine that this document (or another
+     one like it) may have used a prefix of <literal>c</literal> in the past for
+     the same namespace. Since it has changed, the XPath query will no longer 
+     return the proper results and the query will require modification. Using 
+     <literal>registerXPathNamespace</literal> avoids future modification of the
+     query even if the provider changes the namespace prefix.
+    </para>
+   </example>
+  </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><xref linkend="function.simplexml-element-getDocNamespaces" /></member>
+    <member><xref linkend="function.simplexml-element-getNamespaces" /></member>
+   </simplelist>
+  </para>
+ </refsect1>
+</refentry>
+
+<!-- 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
+-->

reference/simplexml/functions/simplexml-load-file.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.13 $ -->
+<!-- $Revision: 1.14 $ -->
   <refentry id='function.simplexml-load-file'>
    <refnamediv>
     <refname>simplexml_load_file</refname>
@@ -14,6 +14,8 @@
      <methodparam><type>string</type><parameter>filename</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>class_name</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>options</parameter></methodparam>
+     <methodparam choice="opt"><type>string</type><parameter>ns</parameter></methodparam>
+     <methodparam choice="opt"><type>bool</type><parameter>is_prefix</parameter></methodparam>
     </methodsynopsis>
     <para>
      This function will convert the well-formed XML document in the file

reference/simplexml/functions/simplexml-load-string.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.10 $ -->
+<!-- $Revision: 1.11 $ -->
   <refentry id='function.simplexml-load-string'>
    <refnamediv>
     <refname>simplexml_load_string</refname>
@@ -14,6 +14,8 @@
      <methodparam><type>string</type><parameter>data</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>class_name</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>options</parameter></methodparam>
+     <methodparam choice="opt"><type>string</type><parameter>ns</parameter></methodparam>
+     <methodparam choice="opt"><type>bool</type><parameter>is_prefix</parameter></methodparam>
     </methodsynopsis>
     <para>
      This function will take the well-formed xml string