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

Copy
1<?php
2
3/**
4 * Dom\DocumentFragment::C14N メソッドの使用例を示します。
5 *
6 * C14N (Canonical XML) は、XMLドキュメントの正規化形式を生成する標準です。
7 * 論理的に等価なXMLドキュメントは、C14N化されると常に同じバイト列に変換されます。
8 * この例では、Dom\DocumentFragment を使用してXMLスニペットをC14N化します。
9 */
10function demonstrateDocumentFragmentC14N(): void
11{
12    // C14N化するXML文字列を定義します。
13    // 属性の順序、コメント、要素間の空白など、C14Nによって正規化される要素を含めます。
14    $xmlString = <<<XML
15<root attr2="value2" attr1="value1">
16    <!-- このコメントはデフォルトのC14N化の結果には含まれません -->
17    <item>Hello &amp; World!</item>
18</root>
19XML;
20
21    echo "--- 元のXML文字列 ---\n";
22    echo $xmlString . "\n\n";
23
24    try {
25        // Dom\DocumentFragment を作成します。
26        // これは、XMLドキュメントの一部を扱うための特殊なノードです。
27        $fragment = new Dom\DocumentFragment();
28
29        // XMLコンテンツをフラグメントに追加します。
30        // この操作が失敗する可能性もあるため、結果を確認します。
31        if (!$fragment->appendXML($xmlString)) {
32            echo "エラー: DocumentFragment への XML コンテンツの追加に失敗しました。\n";
33            return;
34        }
35
36        // C14N メソッドを呼び出します。
37        // 引数なしの場合、デフォルトのC14N (非排他的、コメントなし) が適用されます。
38        $c14nResult = $fragment->C14N();
39
40        // C14N 処理が成功したか確認し、結果を出力します。
41        if ($c14nResult === false) {
42            echo "エラー: C14N 処理中に問題が発生しました。\n";
43        } else {
44            echo "--- C14N化されたXML文字列 (デフォルト設定) ---\n";
45            echo $c14nResult . "\n";
46            echo "\n注: 属性の順序がアルファベット順に正規化され、コメントや余分な空白が除去されています。\n";
47        }
48
49    } catch (Throwable $e) {
50        // 処理中に発生した例外を捕捉し、エラーメッセージを出力します。
51        echo "処理中にエラーが発生しました: " . $e->getMessage() . "\n";
52    }
53}
54
55// 上記で定義した関数を実行し、C14Nの動作を確認します。
56demonstrateDocumentFragmentC14N();
57

このサンプルコードは、PHP 8 の Dom\DocumentFragment::C14N メソッドを利用し、XMLドキュメントの一部を正規化する方法を示しています。C14N（Canonical XML）とは、論理的に同じXMLドキュメントが常に同じバイト列に変換されるよう標準化する技術です。これにより、XMLの比較やデジタル署名などで一貫性が保証されます。

コードでは、まず正規化したいXML文字列を定義します。このXMLには、属性の順序やコメントなど、C14Nによって正規化される要素を含ませています。次に、Dom\DocumentFragmentというXMLの断片を扱うための特殊なノードを作成し、定義したXML文字列を追加します。

その後、C14N()メソッドを呼び出します。このメソッドは、引数として$exclusive（排他正規化）、$withComments（コメントを含めるか）、$xpath（正規化対象の指定）、$nsPrefixes（名前空間プレフィックスの指定）を受け取りますが、サンプルでは引数なしで呼び出し、デフォルト設定（非排他的、コメントなし）で動作させています。

メソッドが成功すると、正規化されたXML文字列が返されます。失敗した場合はfalseが返されるため、処理結果を確認することが重要です。出力された正規化済みXMLでは、属性の順序がアルファベット順に整理され、コメントや余分な空白が除去されていることが確認できます。

Copy
1<?php
2
3/**
4 * Dom\DocumentFragment::C14N を使用してXML文書断片を正規化するサンプル関数
5 *
6 * この関数は、DOMDocumentFragmentを作成し、いくつかのノードを追加した後、
7 * C14Nメソッドの引数を変えながら正規化（Canonicalization）された
8 * XML文字列を生成し、その結果を出力します。
9 * C14Nは、論理的に等価なXML文書がバイトレベルでも同一の表現になるように
10 * 変換するためのW3C標準規格です。電子署名などで利用されます。
11 */
12function generateCanonicalXmlFragmentExample(): void
13{
14    // PHP 8のDOM拡張機能を使用
15    $dom = new \Dom\Document();
16
17    // 1. DocumentFragmentを作成します。
18    // これは文書全体ではなく、XMLの一部を保持するための軽量なコンテナです。
19    $fragment = $dom->createDocumentFragment();
20
21    // 2. フラグメントに様々なノードを追加します。
22    // コメントノード
23    $fragment->appendChild($dom->createComment(' comment '));
24
25    // 名前空間を持つ要素
26    $parent = $dom->createElementNS('https://example.com/ns', 'ns:parent');
27    $parent->setAttribute('attr', 'value');
28    $fragment->appendChild($parent);
29
30    // テキストを持つ子要素
31    $child = $dom->createElement('child');
32    $child->appendChild($dom->createTextNode('Hello World'));
33    $parent->appendChild($child);
34
35
36    // 3. C14N() メソッドを実行して正規化された文字列を取得します。
37    // 引数を変更することで、出力形式を制御できます。
38
39    // ケース1: デフォルト (exclusive: false, withComments: false)
40    // コメントは除去され、名前空間の定義はそのまま出力されます。
41    echo "--- Default C14N (non-exclusive, no comments) ---\n";
42    $defaultResult = $fragment->C14N();
43    echo $defaultResult . "\n\n";
44
45    // ケース2: コメントを含む (withComments: true)
46    echo "--- C14N with comments ---\n";
47    $withCommentsResult = $fragment->C14N(false, true);
48    echo $withCommentsResult . "\n\n";
49
50    // ケース3: 排他的正規化 (exclusive: true)
51    // その要素のコンテキストで実際に使用されている名前空間のみが出力されます。
52    echo "--- Exclusive C14N ---\n";
53    $exclusiveResult = $fragment->C14N(true, false);
54    echo $exclusiveResult . "\n";
55}
56
57// 関数を実行して結果を表示
58generateCanonicalXmlFragmentExample();
59

このPHPサンプルコードは、Dom\DocumentFragment::C14Nメソッドを使い、XML文書の一部分を正規化する方法を示しています。正規化（Canonicalization）とは、論理的に同じ意味を持つXMLが、バイトレベルで完全に同一の文字列表現になるよう変換するW3C標準のルールのことで、主に電子署名の検証などで利用されます。

コードでは、まずDocumentFragmentオブジェクトを作成し、コメントや名前空間を持つ要素ノードを追加して、XMLの断片を構築します。DocumentFragmentは、文書全体ではなく、その一部を保持するための軽量なコンテナとして機能します。

その後、この断片に対してC14Nメソッドを異なる引数で呼び出し、出力結果を比較しています。第一引数の$exclusiveをtrueにすると「排他的正規化」となり、その断片内で実際に使用されている名前空間定義のみが出力されます。第二引数の$withCommentsをtrueにすると、出力にコメントが含まれます。引数を指定しない場合は、コメントは除去され、排他的ではない通常の正規化が行われます。このメソッドは、処理に成功すると正規化されたXML文字列を返し、失敗した場合はfalseを返します。このように、引数を調整することで、要件に応じた形式でXMLを標準化できます。