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

Copy
1<?php
2
3/**
4 * DOMComment::C14N メソッドの使用例を示します。
5 *
6 * このメソッドはXMLのコメントノードをXML正規化 (Canonicalization) のルールに従って文字列に変換します。
7 * XML正規化とは、XMLドキュメントの内容に意味的な変更を与えずに、標準的な物理表現に変換するプロセスです。
8 * 主にXML署名などで、ドキュメントの比較や署名対象の決定に使われます。
9 *
10 * @param bool $exclusive 排他的C14Nを適用するかどうか。名前空間の宣言の扱いに影響しますが、
11 *                        コメントノード単独の場合、その影響は限定的です。
12 * @param bool $withComments コメントノード自体をC14Nの結果文字列に含めるかどうか。
13 *                           falseの場合、コメントノードは正規化の結果に含まれないため、
14 *                           このメソッドは bool(false) を返します。
15 * @return void
16 */
17function demonstrateDomCommentC14nUsage(bool $exclusive, bool $withComments): void
18{
19    // 1. 新しいDOMドキュメントを作成
20    $dom = new DOMDocument('1.0', 'UTF-8');
21    $dom->formatOutput = true; // 出力を見やすく整形します
22
23    // ルート要素を作成し、ドキュメントに追加
24    $root = $dom->createElement('example');
25    $dom->appendChild($root);
26
27    // テスト用のコメントノードを作成し、ルート要素に追加
28    // コメント内部のコンテンツの前後のスペースはC14Nでも保持されます。
29    $commentContent = ' This is a sample comment. ';
30    $commentNode = $dom->createComment($commentContent);
31    $root->appendChild($commentNode);
32
33    echo "--- 実行条件: exclusive=" . ($exclusive ? 'true' : 'false') . ", withComments=" . ($withComments ? 'true' : 'false') . " ---\n";
34    echo "  元のコメントノードのXML表現: " . $dom->saveXML($commentNode) . "\n";
35
36    // 2. DOMComment::C14N メソッドを呼び出す
37    //    このメソッドは、呼び出し元のコメントノードを正規化し、その結果を文字列で返します。
38    //    withComments が false の場合、コメントノード自体が結果に含まれないため false を返します。
39    $c14nResult = $commentNode->C14N($exclusive, $withComments);
40
41    // 3. 結果を出力
42    echo "  C14Nの結果 (型: " . gettype($c14nResult) . "): ";
43    if ($c14nResult === false) {
44        echo "false (withComments=false のため、コメントノードはC14Nの結果に含まれません)\n";
45    } else {
46        echo var_export($c14nResult, true) . "\n";
47    }
48    echo "\n";
49}
50
51// --- さまざまな引数の組み合わせで demonstrateDomCommentC14nUsage 関数を実行 ---
52
53// ケース1: withComments=false の場合
54//   コメントノードはC14Nの結果に含まれないため、メソッドは常に 'false' を返します。
55demonstrateDomCommentC14nUsage(exclusive: false, withComments: false);
56demonstrateDomCommentC14nUsage(exclusive: true, withComments: false);
57
58// ケース2: withComments=true の場合
59//   コメントノードが正規化された形式で文字列として返されます。
60//   コメントの区切り記号 (<!-- と -->) と内部のテキストがそのまま含まれます。
61//   exclusive の影響は、コメントノード単独ではほとんど見られません。
62demonstrateDomCommentC14nUsage(exclusive: false, withComments: true);
63demonstrateDomCommentC14nUsage(exclusive: true, withComments: true);
64
65?>

PHPのDOMComment::C14Nメソッドは、XMLのコメントノードをXML正規化 (Canonicalization) のルールに従って文字列に変換するために使用されます。XML正規化とは、XMLドキュメントの内容に意味的な変更を与えずに、標準的な物理表現に統一するプロセスです。これは主にXML署名などで、ドキュメントの比較や同一性確認に利用されます。

このメソッドは、呼び出し元のコメントノードに対し、正規化処理を適用した結果を返します。引数$exclusiveは排他的C14Nを適用するかどうかを指定しますが、コメントノード単独ではその影響は限定的です。重要な引数である$withCommentsをtrueに設定すると、コメントノード自体（<!-- ... -->を含む）が正規化された文字列として返されます。一方、$withCommentsがfalseの場合は、コメントノードがC14Nの結果に含まれないため、メソッドはfalseを返します。

戻り値は、正規化されたコメント文字列 (string)、またはコメントを含まない場合にfalseとなります。サンプルコードでは、DOMDocumentで作成したコメントノードに対してC14Nメソッドを異なる引数で実行し、$withCommentsがfalseのときにfalseが返される挙動など、具体的な出力結果を通してその動作を示しています。

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * DOMComment::C14N メソッドの使用例を示します。
7 *
8 * XMLドキュメント内のコメントノードを正規化 (Canonicalize) する方法を解説します。
9 * C14N (Canonical XML) は、論理的に同じXML文書が、物理的に異なる表現
10 * (例: 属性の順序、空白文字) であっても、同一のバイト表現になるように変換する仕様です。
11 *
12 * このサンプルでは、コメントノードに対して C14N() メソッドを呼び出し、
13 * 第2引数 $withComments の違いによる出力の変化を確認します。
14 *
15 * 注意: PHPのDOM拡張機能が実装しているのは Canonical XML Version 1.0 です。
16 */
17function demonstrateDomCommentC14N(): void
18{
19    // サンプルとなるXML文字列を定義
20    $xmlString = <<<XML
21<?xml version="1.0" encoding="UTF-8"?>
22<root>
23    <!-- This is a target comment -->
24    <element attribute="value">Content</element>
25</root>
26XML;
27
28    // DOMDocumentオブジェクトを作成し、XMLを読み込む
29    $document = new DOMDocument();
30    $document->loadXML($xmlString);
31
32    // XPathを使用して最初のコメントノードを取得する
33    $xpath = new DOMXPath($document);
34    $commentNodes = $xpath->query('//comment()');
35
36    if ($commentNodes === false || $commentNodes->length === 0) {
37        echo 'Target comment node not found.' . PHP_EOL;
38        return;
39    }
40
41    /** @var DOMComment $targetCommentNode */
42    $targetCommentNode = $commentNodes->item(0);
43
44    // --- 1. コメントを含めずに正規化 (デフォルトの動作) ---
45    // 第2引数 $withComments を false (または省略) に設定します。
46    // コメントノード自体には子ノードがないため、正規化された出力は空文字列になります。
47    echo '--- C14N with $withComments = false (default) ---' . PHP_EOL;
48    $c14nString1 = $targetCommentNode->C14N(false, false);
49    var_dump($c14nString1);
50    echo PHP_EOL;
51
52    // --- 2. コメントを含めて正規化 ---
53    // 第2引数 $withComments を true に設定します。
54    // これにより、コメントノード自体が正規化された出力に含まれます。
55    echo '--- C14N with $withComments = true ---' . PHP_EOL;
56    $c14nString2 = $targetCommentNode->C14N(false, true);
57    var_dump($c14nString2);
58    echo PHP_EOL;
59}
60
61// 関数を実行して結果を表示
62demonstrateDomCommentC14N();
63

PHP 8のDOMComment::C14Nメソッドは、XMLドキュメント内のコメントノードを正規化（Canonicalize）するために使用されます。正規化とは、論理的に同じXML文書が、属性の順序や空白文字などの物理的な表現の違いに関わらず、常に同一のバイト表現になるように変換する標準仕様（C14N）のことです。

このメソッドは、DOMCommentクラスに属し、特定のコメントノードに対して呼び出します。引数としては、排他的正規化を行うかどうかを指定する$exclusive（デフォルトはfalse）、正規化された出力にコメントノード自体を含めるかどうかを指定する$withComments（デフォルトはfalse）などを受け取ります。その他、特定のノードセットを対象にする$xpathや$nsPrefixes引数もありますが、この例ではコメントノード全体を扱っています。メソッドの戻り値は、成功した場合は正規化されたXML文字列を、失敗した場合はfalseを返します。

サンプルコードでは、XML文字列から特定のコメントノードを取得し、$withComments引数の違いによる挙動を示しています。$withCommentsをfalseに設定した場合、コメントノード自体は子要素を持たないため、正規化された出力は空文字列となります。これに対し、$withCommentsをtrueに設定すると、コメントノードの内容（例: <!-- This is a target comment -->）が正規化された形式で文字列として出力されます。これにより、XMLの署名など、厳密な比較が求められる場面でコメントノードの表現を統一することが可能になります。