【PHP8.x】Dom\Text::C14N()メソッドの使い方

Copy
1<?php
2
3/**
4 * XML文字列を正規化（Canonical XML）するサンプル関数。
5 *
6 * PHPのDOM拡張において、XMLノードのC14N（Canonical XML）形式への変換を示します。
7 * C14Nは、XMLのバイト表現を一意に決定するために使用され、デジタル署名などで重要です。
8 *
9 * PHP 8以降の新しいDOM拡張クラス (`Dom\` 名前空間) を使用しています。
10 *
11 * @param string $xmlString 正規化するXML文字列。
12 * @return void
13 */
14function demonstrateXmlC14n(string $xmlString): void
15{
16    // Dom\Document オブジェクトを作成
17    $dom = new Dom\Document();
18    
19    // XML読み込み時のホワイトスペースの扱いを設定 (C14Nには影響しないが、出力整形のため)
20    $dom->preserveWhiteSpace = false;
21    $dom->formatOutput = true;
22
23    // XML文字列を読み込む
24    if (!$dom->loadXML($xmlString)) {
25        // XMLの読み込みに失敗した場合
26        echo "エラー: XMLの読み込みに失敗しました。\n";
27        return;
28    }
29
30    // ドキュメントのルート要素を取得します。
31    // Dom\ElementはDom\Nodeを継承しており、C14Nメソッドを持っています。
32    // 補足: 提供されたリファレンス情報にある「Dom\Text::C14N」メソッドは、
33    // PHPの標準DOM拡張には存在しません。
34    // 最も近い機能を持つのはDom\Nodeクラス（またはその子孫）のC14Nメソッドであり、
35    // 通常は要素ノードに対して実行されます。
36    $nodeToC14N = $dom->documentElement;
37
38    if ($nodeToC14N === null) {
39        echo "エラー: ドキュメントにルート要素が見つかりません。\n";
40        return;
41    }
42
43    echo "--- オリジナルのXMLを整形して表示 ---\n";
44    // CLIでの出力を見やすくするため、XMLの特殊文字をエスケープして表示
45    echo htmlspecialchars($dom->saveXML()) . "\n\n";
46
47    // 1. デフォルトの正規化 (exclusive=false, withComments=false)
48    // 名前空間プレフィックスは元のままで、コメントは含まれません。
49    echo "--- C14N (基本) ---\n";
50    $c14nResult = $nodeToC14N->C14N();
51    if ($c14nResult !== false) {
52        echo htmlspecialchars($c14nResult) . "\n\n";
53    } else {
54        echo "C14N (基本) に失敗しました。\n\n";
55    }
56
57    // 2. コメントを含む正規化 (withComments=true)
58    // XMLコメントも正規化された出力に含まれます。
59    echo "--- C14N (コメントを含む) ---\n";
60    $c14nWithComments = $nodeToC14N->C14N(false, true);
61    if ($c14nWithComments !== false) {
62        echo htmlspecialchars($c14nWithComments) . "\n\n";
63    } else {
64        echo "C14N (コメントを含む) に失敗しました。\n\n";
65    }
66
67    // 3. 排他的正規化 (exclusive=true)
68    // これは、ノードセット内の要素に宣言された名前空間プレフィックスのみを含むようにします。
69    // 子要素に宣言された名前空間は含まれず、より簡潔な正規化形式を生成します。
70    echo "--- C14N (排他的) ---\n";
71    $c14nExclusive = $nodeToC14N->C14N(true, false);
72    if ($c14nExclusive !== false) {
73        echo htmlspecialchars($c14nExclusive) . "\n\n";
74    } else {
75        echo "C14N (排他的) に失敗しました。\n\n";
76    }
77}
78
79// サンプルXMLデータ
80$sampleXml = <<<XML
81<root xmlns="http://example.com/default" xmlns:pref="http://example.com/pref">
82    <child id="1" pref:attr="val">
83        <textNode>Hello</textNode>
84    </child>
85    <!-- これはコメントです -->
86    <anotherChild>
87        <data>World</data>
88    </anotherChild>
89</root>
90XML;
91
92// 関数を実行してC14Nの動作を確認
93demonstrateXmlC14n($sampleXml);

このサンプルコードは、PHP 8の新しいDOM拡張機能を用いてXML文書を正規化（Canonical XML、略称C14N）する方法を示しています。C14Nとは、XML文書のバイト表現を一意に決定する国際標準であり、デジタル署名などでXMLの内容が改ざんされていないかを確認する際に重要となります。

提供されたリファレンス情報ではDom\Textクラスのメソッドとありますが、実際にはDom\Nodeクラス（またはその子孫であるDom\Elementなど）がC14Nメソッドを提供しており、サンプルコードではドキュメントのルート要素（Dom\Elementインスタンス）に対してこのメソッドを呼び出しています。

C14Nメソッドは、XMLノードを正規化された文字列として返します。引数$exclusiveをtrueにすると排他的な正規化が行われ、名前空間の宣言がより簡潔になります。$withCommentsをtrueにすると、コメントも正規化された出力に含まれます。その他の引数$xpathや$nsPrefixesを使用すると、正規化の対象範囲や名前空間の扱いをさらに細かく制御できますが、このサンプルでは使用していません。

メソッドの戻り値は、正規化に成功した場合はstring型のXML文字列、失敗した場合はfalseです。サンプルコードでは、基本的な正規化、コメントを含む正規化、排他的な正規化という3つのパターンを実行し、それぞれの出力の違いを確認できるようになっています。

Copy
1<?php
2
3/**
4 * Dom\Text::C14N メソッドの使用例。
5 * XMLテキストノードの正規化された形式を取得します。
6 *
7 * C14N (Canonicalization) とは、XML文書のさまざまな表現を単一の標準形式に変換するプロセスです。
8 * これにより、XML文書の内容が同一であるかを比較する際に役立ちます。
9 * Dom\Text::C14N メソッドは、指定されたテキストノードの正規化された形式を返します。
10 *
11 * 注: 通常、C14NはXMLドキュメント全体や特定の要素に対して適用されます。
12 * テキストノード単体に対して適用する場合、そのテキスト内容がそのまま返されることが多いです。
13 * リファレンス情報にある引数 ($xpath, $nsPrefixes) は、通常 DOMDocument や DOMElement の C14N メソッドで
14 * 使用され、Dom\Text クラスの C14N メソッドでは一般的なユースケースが少ないため、
15 * ここではそれらを省略し、基本的な使用法に焦点を当てます。引数を省略した場合、デフォルト値 (null) が使用されます。
16 */
17function demonstrateDomTextC14N(): void
18{
19    // サンプルXML文字列
20    $xmlString = <<<XML
21<root xmlns="http://example.com/ns" xmlns:pref="http://example.com/pref">
22    <element attr="value &amp; test">
23        Hello
24        <!-- This is a comment -->
25        World!
26    </element>
27    <another>Simple Text</another>
28</root>
29XML;
30
31    // DOMDocument オブジェクトを作成し、XMLをロード
32    $dom = new DOMDocument();
33    $dom->loadXML($xmlString);
34    // 空白ノードを無視することで、目的のテキストノードにアクセスしやすくする
35    $dom->preserveWhiteSpace = false;
36
37    // <element> 要素を取得
38    $element = $dom->getElementsByTagName('element')->item(0);
39
40    if (!$element) {
41        echo "エラー: XML内に 'element' タグが見つかりませんでした。\n";
42        return;
43    }
44
45    // <element> 要素の子ノードを走査し、Dom\Text ノードを探す
46    $textNode = null;
47    foreach ($element->childNodes as $node) {
48        // PHP 8 では Dom\Text を使用。DOMText と同じです。
49        if ($node instanceof Dom\Text) {
50            $textNode = $node;
51            break; // 最初のテキストノードが見つかったら終了
52        }
53    }
54
55    if (!$textNode) {
56        echo "エラー: 'element' 内にテキストノードが見つかりませんでした。\n";
57        return;
58    }
59
60    echo "--- 元のテキストノードの値 ---\n";
61    // テキストノードの値から改行や余分な空白を除去して表示
62    echo "'" . trim($textNode->nodeValue) . "'\n\n";
63
64    // 1. デフォルトオプション (非排他的, コメントなし) で C14N を実行
65    // テキストノードの場合、通常は元のテキスト値がそのまま返されます。
66    $c14nDefault = $textNode->C14N();
67    if ($c14nDefault !== false) {
68        echo "--- C14N 結果 (デフォルトオプション: exclusive=false, withComments=false) ---\n";
69        echo "'" . $c14nDefault . "'\n\n";
70    } else {
71        echo "C14N がデフォルトオプションで失敗しました。\n\n";
72    }
73
74    // 2. コメントを含めるオプション (withComments = true) で C14N を実行
75    // テキストノード自体はコメントを持たないため、このオプションは結果に影響を与えません。
76    $c14nWithComments = $textNode->C14N(false, true);
77    if ($c14nWithComments !== false) {
78        echo "--- C14N 結果 (withComments=true) ---\n";
79        echo "'" . $c14nWithComments . "'\n\n";
80    } else {
81        echo "C14N が withComments=true オプションで失敗しました。\n\n";
82    }
83
84    // 3. 排他的正規化オプション (exclusive = true) で C14N を実行
85    // テキストノード単体では、このオプションも通常は結果に影響を与えません。
86    // 排他的正規化は、通常は要素やドキュメントレベルで名前空間の扱いを制御する際に重要になります。
87    $c14nExclusive = $textNode->C14N(true, false);
88    if ($c14nExclusive !== false) {
89        echo "--- C14N 結果 (exclusive=true) ---\n";
90        echo "'" . $c14nExclusive . "'\n\n";
91    } else {
92        echo "C14N が exclusive=true オプションで失敗しました。\n\n";
93    }
94}
95
96// 関数を実行
97demonstrateDomTextC14N();
98

PHP 8のDom\Text::C14Nメソッドは、XMLのテキストノードを正規化された形式に変換します。C14N（Canonicalization）とは、XML文書の表記揺れを吸収し、内容が同一であるかを比較できるように、標準的な形式に整えるプロセスです。このサンプルコードでは、XML文字列からDOMDocumentを生成し、特定の要素内のテキストノードを抽出して、そのテキストノードに対してC14Nメソッドを適用しています。

C14Nメソッドは、引数$exclusiveで排他的正規化の有無、$withCommentsでコメントを含めるかどうかを指定できます。また、$xpathで正規化対象をXPathで指定したり、$nsPrefixesで名前空間プレフィックスを指定したりすることも可能ですが、Dom\TextクラスのC14Nではこれらの引数が影響することは稀です。メソッドの戻り値は、正規化されたテキスト内容の文字列ですが、処理に失敗した場合はfalseを返します。

テキストノード単体に対するC14Nは、多くの場合、元のテキスト値がそのまま返される傾向にあります。これは、C14Nが主に要素やドキュメント全体における名前空間宣言や属性の表現方法、空白文字の扱いなどを標準化する際に、より顕著な効果を発揮するためです。サンプルコードでは、デフォルトオプション、コメントを含めるオプション、排他的正規化オプションのそれぞれの結果を表示し、その挙動を確認しています。