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

Copy
1<?php
2
3/**
4 * DOMDocument::C14NFile メソッドのサンプルコード
5 * XML ドキュメントを正規化（Canonicalization）し、その結果を指定されたファイルに書き込みます。
6 *
7 * @param string $outputFile 正規化されたXMLを書き込むファイルパス。
8 * @return void
9 */
10function demonstrateC14NFile(string $outputFile): void
11{
12    // 元のXMLデータ
13    // C14N（Canonicalization）の効果を示すため、属性の順序、空要素、コメント、名前空間などを含む
14    $xmlString = <<<XML
15<?xml version="1.0" encoding="UTF-8"?>
16<root xmlns:m="http://example.com/ns/my"  attr2="value2" attr1="value1" >
17    <m:child   />
18    <!-- これはコメントです -->
19    <data>
20        Hello World!
21    </data>
22</root>
23XML;
24
25    echo "--- 元のXML ---" . PHP_EOL;
26    echo $xmlString . PHP_EOL . PHP_EOL;
27
28    // DOMDocumentオブジェクトを作成
29    $dom = new DOMDocument('1.0', 'UTF-8');
30    
31    // XML文字列をDOMDocumentオブジェクトにロード
32    if (!$dom->loadXML($xmlString)) {
33        echo "エラー: XMLのロードに失敗しました。" . PHP_EOL;
34        return;
35    }
36
37    // C14NFileメソッドを呼び出し、正規化されたXMLをファイルに書き込む
38    // 引数:
39    //   $outputFile: 正規化されたXMLを書き込むファイルパス
40    //   false: 包含的正規化 (trueの場合は排他的正規化)
41    //   true: コメントを含める (falseの場合はコメントを含めない)
42    //   null: XPathクエリによるノード選択は行わない (オプション)
43    //   null: 名前空間プレフィックスの指定は行わない (オプション)
44    // 戻り値: 書き込まれたバイト数 (int) または失敗時に false
45    $bytesWritten = $dom->C14NFile($outputFile, false, true, null, null);
46
47    if ($bytesWritten !== false) {
48        echo "--- 正規化されたXML (ファイルに書き込まれました) ---" . PHP_EOL;
49        echo "書き込まれたバイト数: " . $bytesWritten . PHP_EOL;
50        
51        // 書き込まれたファイルの内容を読み込んで表示
52        $c14nContent = file_get_contents($outputFile);
53        if ($c14nContent !== false) {
54            echo $c14nContent . PHP_EOL . PHP_EOL;
55            // C14Nにより、XMLのバイト表現が正規化されます。
56            // 例えば、属性の順序がアルファベット順に統一され、
57            // 空要素（<m:child />）が展開されたりします（<m:child></m:child>）。
58            // `with_comments` を true に設定したため、コメントも出力に含まれます。
59        } else {
60            echo "エラー: 正規化されたファイルの内容を読み取れませんでした。" . PHP_EOL;
61        }
62    } else {
63        echo "エラー: XMLの正規化（C14NFile）に失敗しました。" . PHP_EOL;
64    }
65}
66
67// 一時ファイル名を生成し、権限のある一時ディレクトリにファイルを作成します。
68$tempFile = tempnam(sys_get_temp_dir(), 'c14n_example_');
69if ($tempFile === false) {
70    // 一時ファイルの作成に失敗した場合はエラーを出力して終了
71    echo "エラー: 一時ファイルの作成に失敗しました。一時ディレクトリの書き込み権限を確認してください。" . PHP_EOL;
72    exit(1);
73}
74
75// サンプル関数の実行
76demonstrateC14NFile($tempFile);
77
78// 不要になった一時ファイルを削除します。
79if (file_exists($tempFile)) {
80    unlink($tempFile);
81}

DOMDocument::C14NFileメソッドは、XMLドキュメントを正規化（Canonicalization）し、その結果を指定されたファイルに書き込むための機能です。XMLの正規化とは、同じ内容のXMLであっても記述形式の違い（属性の順序、空要素の記述方法、改行など）を統一し、システム間での比較を容易にしたり、デジタル署名に適した一貫性のある形にしたりするプロセスを指します。

このサンプルコードでは、まずXML文字列をDOMDocumentオブジェクトに読み込みます。次に、C14NFileメソッドを呼び出し、正規化されたXMLを指定された一時ファイルに保存しています。引数 $uri には、正規化されたXMLを書き出すファイルのパスを指定します。$exclusive は正規化の種類（排他的か包含的か）を制御し、この例では false で包含的正規化を行っています。$with_comments はXMLコメントを正規化結果に含めるかどうかを決め、ここでは true でコメントを含めて出力しています。オプションの $xpath や $ns_prefixes は、正規化の対象を特定のXMLノードに限定する場合に利用しますが、この例では null を指定してドキュメント全体を対象としています。

メソッドの戻り値は、ファイルに書き込まれたデータのバイト数（整数値）か、処理が失敗した場合は false です。正規化されたXMLでは、属性がアルファベット順に並べ替えられたり、空要素の記述が <tag/> から <tag></tag> のように統一されたりするなど、XMLの表現が一貫したものになることを確認できます。

Copy
1<?php
2
3/**
4 * DOMComment::C14NFile メソッドを使用して、XMLコメントノードを正規化形式でファイルに保存するサンプル。
5 *
6 * この関数は、XMLドキュメントからDOMCommentノードを抽出し、そのコメントノードのみを
7 * XML正規化形式（C14N 1.0）で指定されたファイルに保存する方法を示します。
8 * C14Nは、XMLドキュメントのバイト表現を標準化し、一貫した形式を保証するために使用されます。
9 *
10 * @param string $outputFilePath 正規化されたコメントを保存するファイルのパス。
11 * @return bool 処理が成功した場合は true、失敗した場合は false。
12 */
13function saveCommentNodeCanonicalizedToFile(string $outputFilePath): bool
14{
15    // 1. DOMDocument オブジェクトを作成し、サンプルXMLをロードします。
16    //    C14NFile メソッドの対象となるコメントノードを含むXMLを用意します。
17    $dom = new DOMDocument('1.0', 'UTF-8');
18    $xmlString = <<<XML
19<root>
20    <element>
21        <!-- これはテスト用のコメントです -->
22        <item>データ</item>
23    </element>
24    <!-- 別のコメント -->
25</root>
26XML;
27    // XMLをロードし、空白ノードを削除して扱いやすくします。
28    $dom->loadXML($xmlString, LIBXML_NOBLANKS);
29
30    // 2. DOMComment ノードを特定します。
31    //    ここでは DOMXPath を使用して、ドキュメント内の最初のコメントノードを見つけます。
32    $xpath = new DOMXPath($dom);
33    $commentNodes = $xpath->query('//comment()');
34
35    if ($commentNodes === false || $commentNodes->length === 0) {
36        echo "エラー: XMLドキュメント内にコメントノードが見つかりませんでした。\n";
37        return false;
38    }
39
40    // 最初のコメントノードを取得します。
41    $commentNode = $commentNodes->item(0);
42
43    echo "対象のコメントノードの内容: \"" . $commentNode->nodeValue . "\"\n";
44    echo "出力先ファイルパス: " . $outputFilePath . "\n";
45
46    // 3. DOMComment::C14NFile メソッドを呼び出し、コメントノードをファイルに正規化します。
47    //    DOMComment クラスは DOMNode を継承しているため、C14NFile メソッドを利用できます。
48    //
49    //    引数について:
50    //    - $outputFilePath (string): 正規化された出力の保存先URI (ファイルパス)。
51    //    - $exclusive (bool): 排他的正規化を使用するかどうか。通常は false (非排他的)。
52    //    - $with_comments (bool): コメントノードを出力に含めるかどうか。
53    //      DOMCommentノード自体を保存する場合は 'true' に設定しないと、出力は空になります。
54    //    - $xpath (array|null): 正規化するサブセットを指定するXPath式。今回はノード自体なので指定不要。
55    //    - $ns_prefixes (array|null): 名前空間プレフィックスのリスト。今回は名前空間を使用しないため指定不要。
56    $result = $commentNode->C14NFile(
57        $outputFilePath,
58        false, // $exclusive: 排他的正規化は行いません。
59        true   // $with_comments: コメントノードを正規化出力に含めます。
60               // これを false にすると、コメントノードは出力から除外され、空のファイルが作成されます。
61    );
62
63    if ($result === false) {
64        echo "エラー: コメントノードのファイルへの正規化に失敗しました。\n";
65        return false;
66    }
67
68    echo "コメントノードが正常にファイルに正規化されました。\n";
69    echo "--- {$outputFilePath} の内容 ---\n";
70    echo file_get_contents($outputFilePath) . "\n";
71    echo "----------------------------\n";
72
73    // 4. クリーンアップ: 処理後に作成されたファイルを削除します。
74    if (file_exists($outputFilePath)) {
75        unlink($outputFilePath);
76        echo "作成されたファイル '{$outputFilePath}' を削除しました。\n";
77    }
78
79    return true;
80}
81
82// スクリプトの実行例:
83// スクリプトが実行されているディレクトリに 'canonicalized_comment.xml' という名前でファイルが作成されます。
84$targetFile = __DIR__ . '/canonicalized_comment.xml';
85saveCommentNodeCanonicalizedToFile($targetFile);
86

PHP 8のDOMComment::C14NFileメソッドは、XMLドキュメント内のコメントノードをXML正規化形式（C14N 1.0）で指定されたファイルに保存する機能を提供します。C14Nは、XMLドキュメントのバイト表現を標準化し、一貫した形式を保証するための技術です。

このサンプルコードでは、まずDOMDocumentオブジェクトを作成し、コメントを含むXML文字列を読み込みます。次に、DOMXPathを使用してドキュメント内の最初のコメントノードを特定しています。

その後、特定したコメントノードに対しC14NFileメソッドを呼び出し、正規化されたコメントをファイルに書き込みます。第一引数$uriには正規化されたコメントを保存するファイルのパスを指定します。重要なのは第三引数$with_commentsで、これをtrueに設定しないとコメントノード自体は出力されず、空のファイルが作成されますので注意が必要です。第二引数$exclusiveは排他的正規化を行うか否かを指定し、通常はfalseで非排他的正規化が行われます。$xpathや$ns_prefixesは、正規化するXMLのサブセットや名前空間を限定する場合に利用しますが、今回はコメントノード自体を対象とするため省略されています。

このメソッドは、処理が成功した場合は正規化されたXML文字列を返し、失敗した場合はfalseを返します。これにより、特定のコメントノードが標準化された形式でファイルに保存されます。