Clarify XPath usage in DOMNode::C14N(File)

php/doc-en@2a72c95
php · May 12, 2024 · fad110d · fad110d
1 parent 682fd6c
commit fad110d
Show file tree

Hide file tree

Showing 3 changed files with 64 additions and 13 deletions.
diff --git a/language-snippets.ent b/language-snippets.ent
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 21e1338e9721534c00085ff3cff25e2dd2e84dc9 Maintainer: takagi Status: working -->
+<!-- EN-Revision: 2a72c95c0a3773a6404d10602005dc453b024843 Maintainer: takagi Status: working -->
 <!-- Credits: hirokawa,haruki,shimooka,mumumu -->
 
 <!ENTITY installation.enabled.disable 'この拡張モジュールはデフォルトで有効になっています。無効にしたい場合は、次のオプションを指定してコンパイルします。'>
@@ -1652,6 +1652,25 @@ object</parameter></term><listitem><para>手続き型のみ: <function>date_crea
 
 <!ENTITY dom.changelog.previous_hierarchy_exception 'これより前のバージョンでは、エラーコード <constant xmlns="http://docbook.org/ns/docbook">DOM_HIERARCHY_REQUEST_ERR</constant> を持つ <classname xmlns="http://docbook.org/ns/docbook">DOMException</classname> がスローされていました。'>
 
+<!ENTITY dom.c14n.xpath_array '<listitem xmlns="http://docbook.org/ns/docbook">
+  <para>
+   ノードをフィルタする XPath の配列。
+   この配列のそれぞれのエントリは、以下の情報を持つ連想配列です:
+   <itemizedlist>
+    <listitem>
+     <simpara>
+      XPath の式の文字列を含む <literal>query</literal> キー。必須です。
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      名前空間のプレフィックス(keys) を名前空間URI (values) にマップした配列を含む <literal>namespaces</literal> キー。オプションです。
+     </simpara>
+    </listitem>
+   </itemizedlist>
+  </para>
+ </listitem>'>
+
 <!-- FileSystem entities -->
 <!ENTITY fs.emits.warning.on.failure '<para xmlns="http://docbook.org/ns/docbook">
 失敗したときは <constant>E_WARNING</constant> が発生します。

diff --git a/reference/dom/domnode/c14n.xml b/reference/dom/domnode/c14n.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 4f5e2b22575131fa5e9c3004b1c874e1acb06573 Maintainer: takagi Status: ready -->
+<!-- EN-Revision: 2a72c95c0a3773a6404d10602005dc453b024843 Maintainer: takagi Status: ready -->
 
 <refentry xml:id="domnode.c14n" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -43,11 +43,7 @@
    </varlistentry>
    <varlistentry>
     <term><parameter>xpath</parameter></term>
-    <listitem>
-     <para>
-      ノードを絞り込むための <literal>xpath</literal> の配列。
-     </para>
-    </listitem>
+    &dom.c14n.xpath_array;
    </varlistentry>
    <varlistentry>
     <term><parameter>nsPrefixes</parameter></term>
@@ -68,6 +64,46 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>XPath クエリの例</title>
+    <para>
+     以下のコードは、XPath クエリを使ってノードをフィルタし、
+     正規化する高度なやり方を示します。
+    </para>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$dom = new DOMDocument;
+$dom->loadXML(<<<XML
+<root xmlns:food="urn:food">
+    <!-- redundant namespace declaration will be canonicalized -->
+    <food:fruit xmlns:food="urn:food">Apple</food:fruit>
+    <food:fruit>Orange</food:fruit>
+    <food:fruit>Pear</food:fruit>
+    <!-- vegetables here -->
+    <food:vegetable>Lettuce</food:vegetable>
+</root>
+XML);
+echo $dom->C14N(true, false, [
+    "query" => ".//f:fruit|.//f:fruit/text()",
+    "namespaces" => ["f" => "urn:food"],
+]);
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+<food:fruit>Apple</food:fruit><food:fruit>Orange</food:fruit><food:fruit>Pear</food:fruit>
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>

diff --git a/reference/dom/domnode/c14nfile.xml b/reference/dom/domnode/c14nfile.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 4f5e2b22575131fa5e9c3004b1c874e1acb06573 Maintainer: takagi Status: ready -->
+<!-- EN-Revision: 2a72c95c0a3773a6404d10602005dc453b024843 Maintainer: takagi Status: ready -->
 <!-- Credits: mumumu -->
 
 <refentry xml:id="domnode.c14nfile" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
@@ -53,11 +53,7 @@
    </varlistentry>
    <varlistentry>
     <term><parameter>xpath</parameter></term>
-    <listitem>
-     <para>
-      ノードを絞り込むための <literal>xpath</literal> の配列。
-     </para>
-    </listitem>
+    &dom.c14n.xpath_array;
    </varlistentry>
    <varlistentry>
     <term><parameter>nsPrefixes</parameter></term>