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

Copy
1<?php
2
3/**
4 * XMLドキュメントをC14N正規化し、ファイルに書き出すデモンストレーションを行います。
5 *
6 * C14N (Canonical XML) は、XMLドキュメントの正規表現を提供し、
7 * 異なる構文で記述されていても論理的に同一のXMLドキュメントが常に同じ表現になるようにします。
8 * これは主にデジタル署名などで、XMLの内容の同一性を保証するために使用されます。
9 *
10 * @return void
11 */
12function demonstrateC14NFile(): void
13{
14    // 1. 正規化したいXMLドキュメントの内容を準備します。
15    // このXMLには、C14Nで正規化される可能性のある要素（属性の順序、空白、コメント、CDATA）を含めます。
16    $xmlString = <<<XML
17<root>
18    <element attributeB="valueB" attributeA="valueA">
19        Hello, <![CDATA[World]]>! <!-- これはコメントです -->
20    </element>
21    <childNode />
22</root>
23XML;
24
25    // 2. Dom\XMLDocument の新しいインスタンスを作成し、XML文字列をロードします。
26    // Dom\XMLDocument は PHP 8 で導入されたDOMDocumentのエイリアスです。
27    $xmlDocument = new Dom\XMLDocument();
28    $xmlDocument->loadXML($xmlString);
29
30    // 3. 正規化されたXMLを保存する一時ファイルパスを決定します。
31    // sys_get_temp_dir() はOSが提供する一時ディレクトリのパスを返します。
32    $outputFilePath = sys_get_temp_dir() . '/canonicalized_output.xml';
33
34    // 4. Dom\XMLDocument::C14NFile メソッドを使用して、XMLを正規化しファイルに書き出します。
35    // 引数:
36    // - $uri: 正規化されたXMLを書き出すファイルのパス。
37    // - $exclusive: 排他的C14Nを使用するかどうか。通常はfalse（非排他的C14N）。
38    // - $withComments: 正規化された出力にコメントを含めるかどうか。通常はfalse。
39    // 戻り値は書き込まれたバイト数です。失敗した場合は false を返します。
40    $bytesWritten = $xmlDocument->C14NFile($outputFilePath, false, false);
41
42    // 5. 処理結果を確認し、ユーザーにフィードバックします。
43    if ($bytesWritten !== false) {
44        echo "XMLがC14N正規化され、ファイルに正常に書き込まれました。\n";
45        echo "出力ファイル: " . $outputFilePath . "\n";
46        echo "書き込まれたバイト数: " . $bytesWritten . "バイト\n\n";
47
48        echo "--- 正規化されたXMLの内容 ---\n";
49        // HTMLエンティティに変換して、特殊文字がターミナルで正しく表示されるようにします。
50        echo htmlspecialchars(file_get_contents($outputFilePath)) . "\n";
51        echo "---------------------------\n";
52
53        // 必要に応じて、作成した一時ファイルを削除することもできます。
54        // 例: unlink($outputFilePath);
55        // echo "\n一時ファイルを削除しました。\n";
56    } else {
57        echo "XMLのC14N正規化とファイルへの書き込みに失敗しました。\n";
58    }
59}
60
61// demonstrateC14NFile 関数を実行して、処理を開始します。
62demonstrateC14NFile();
63

PHPのDom\XMLDocument::C14NFileメソッドは、XMLドキュメントをC14N（Canonical XML）という標準形式に正規化し、その結果をファイルに書き出すために使用されます。C14Nは、XMLの内容が論理的に同じであれば、記述方法が異なっても常に同じ表現になるように保証する技術で、特にデジタル署名などでXMLの同一性を確認する際に重要です。

このサンプルコードでは、まず準備したXML文字列をDom\XMLDocumentオブジェクトに読み込みます。次に、C14NFileメソッドを呼び出し、正規化されたXMLを一時ファイルに保存しています。第一引数$uriには出力先のファイルパスを指定します。第二引数$exclusiveは排他的C14Nを使用するかどうかを真偽値で指定し、通常はfalse（非排他的C14N）が使われます。第三引数$withCommentsは、正規化後の出力にコメントを含めるかどうかを真偽値で設定します。メソッドの戻り値は、ファイルに書き込まれたバイト数を示す整数値、または処理が失敗した場合にはfalseです。このように、C14NFileメソッドは、XMLの標準化された表現を容易にファイルへ出力するための便利な手段を提供します。

Copy
1<?php
2
3/**
4 * XMLドキュメントを正規化（Canonicalization）し、指定されたファイルパスに保存します。
5 * これは、XMLの内容を標準的な形式に変換し、その結果を新しいファイルに「コピー」（cp）する操作です。
6 *
7 * @param string $xmlContent 正規化するXML文字列。
8 * @param string $outputFilePath 正規化されたXMLを保存するファイルパス。
9 * @return bool 処理が成功した場合は true、失敗した場合は false。
10 */
11function normalizeAndCopyXmlToFile(string $xmlContent, string $outputFilePath): bool
12{
13    // Dom\XMLDocument クラスのインスタンスを作成します。
14    // このオブジェクトはXMLドキュメントをメモリ上で操作するために使用されます。
15    $doc = new Dom\XMLDocument();
16
17    // libxmlのエラーを捕捉するために、内部エラーハンドリングを有効にします。
18    // これにより、XML解析中に発生した警告やエラーをPHPが捕捉し、処理できます。
19    libxml_use_internal_errors(true);
20
21    try {
22        // 提供されたXMLコンテンツをDom\XMLDocumentオブジェクトにロードします。
23        // これにより、XML文字列が解析され、DOMツリー構造がメモリ上に構築されます。
24        $doc->loadXML($xmlContent);
25    } catch (Throwable $e) {
26        // XMLのロード中にエラーが発生した場合、エラーメッセージを表示し、処理を終了します。
27        echo "エラー: XMLのロード中に問題が発生しました: " . $e->getMessage() . "\n";
28        foreach (libxml_get_errors() as $error) {
29            echo "libxmlエラー: " . trim($error->message) . " (コード: {$error->code}, 行: {$error->line})\n";
30        }
31        libxml_clear_errors(); // 読み込み中に発生したlibxmlエラーをクリアします。
32        return false;
33    }
34
35    // Dom\XMLDocument::C14NFile() メソッドを使用して、XMLドキュメントを正規化し、ファイルに保存します。
36    // "C14N" (Canonical XML) とは、XMLドキュメントの内容に意味的な変更を与えずに、
37    // 書式（空白、属性の順序、名前空間宣言など）を標準的かつ一貫性のある形式に変換するプロセスです。
38    // このメソッドは、変換されたXMLを新しいファイルに「コピー」する機能を提供します。
39    //
40    // 引数:
41    // 1. $uri (string): 正規化されたXMLを書き込むファイルパス。
42    // 2. $exclusive (bool, オプション): 排他的正規化を行うかどうか。デフォルトは false (非排他的)。
43    // 3. $withComments (bool, オプション): 正規化された出力にコメントを含めるかどうか。
44    //    デフォルトは false (コメントなし) です。
45    // 戻り値: 正常に書き込まれたバイト数 (int) または、ファイルへの書き込みに失敗した場合 false。
46    $bytesWritten = $doc->C14NFile($outputFilePath, false, false); // 非排他的正規化、コメントなし
47
48    if ($bytesWritten === false) {
49        // ファイルへの書き込みに失敗した場合、エラーメッセージを表示し、処理を終了します。
50        echo "エラー: XMLの正規化とファイルへの保存に失敗しました。\n";
51        // C14NFile自体が直接libxmlエラーを出すことは稀ですが、念のため確認し表示します。
52        foreach (libxml_get_errors() as $error) {
53            echo "libxmlエラー: " . trim($error->message) . " (コード: {$error->code}, 行: {$error->line})\n";
54        }
55        libxml_clear_errors(); // エラーをクリアします。
56        return false;
57    }
58
59    echo "成功: XMLが正規化され、'{$outputFilePath}' に保存されました。書き込まれたバイト数: {$bytesWritten}\n";
60    return true;
61}
62
63// ----------------------------------------------------------------------------------------------------
64// 以下は、上記関数を実際に使用するサンプルコードです。
65// この部分が単体で動作可能な例を提供します。
66// ----------------------------------------------------------------------------------------------------
67
68// サンプルとして使用する元のXMLコンテンツ。
69// 意図的に不規則な空白やコメントを含めて、正規化の効果を確認できるようにしています。
70$originalXml = <<<XML
71<?xml version="1.0" encoding="UTF-8"?>
72<!-- このコメントはデフォルトの正規化 (withComments=false) では削除されます -->
73<root    attr1="value1"   attr2="value2" >
74    <item>
75        Hello World!
76    </item>
77    <element    />
78</root>
79XML;
80
81// 正規化されたXMLを保存する一時的なファイルパス。
82// __DIR__ は現在のスクリプトがあるディレクトリを示します。
83$outputFilePath = __DIR__ . '/canonical_output.xml';
84
85echo "--- 元のXMLコンテンツ ---\n";
86echo $originalXml . "\n\n";
87
88// 定義した関数を呼び出し、XMLを正規化してファイルに保存します。
89if (normalizeAndCopyXmlToFile($originalXml, $outputFilePath)) {
90    echo "\n--- 正規化されたXMLファイル '{$outputFilePath}' の内容 ---\n";
91    // 成功した場合、生成されたファイルの内容を読み込んで表示します。
92    // これにより、正規化によってどのようにXMLが変化したかを確認できます。
93    if (file_exists($outputFilePath)) {
94        echo file_get_contents($outputFilePath) . "\n\n";
95
96        // 後処理として、生成された一時ファイルを削除します。
97        unlink($outputFilePath);
98        echo "情報: 生成された一時ファイル '{$outputFilePath}' を削除しました。\n";
99    } else {
100        echo "エラー: ファイル '{$outputFilePath}' が見つかりませんでした。\n";
101    }
102} else {
103    echo "\n処理は失敗しました。\n";
104}

このサンプルコードは、PHP 8 のDom\XMLDocumentクラスに属するC14NFileメソッドを使用して、XMLドキュメントを「正規化」し、その結果を指定されたファイルに保存する方法を示しています。

C14NFileメソッドは、XMLの内容に意味的な変更を与えずに、空白や属性の順序などを標準的かつ一貫性のある形式に変換する「Canonical XML」（C14N）という処理を行います。このメソッドは変換されたXMLを指定のファイルに書き出すため、XMLファイルを標準形式に変換して「コピー」（cp）する機能として利用できます。

コードではまず、Dom\XMLDocumentオブジェクトを作成し、loadXML()メソッドで元のXML文字列をメモリに読み込みます。その後のC14NFile()メソッドの呼び出しでは、最初の引数$uriに正規化されたXMLを保存するファイルパスを指定します。$exclusive引数は排他的正規化を行うか、$withComments引数はコメントを含めるかを真偽値で設定できますが、サンプルでは両方ともfalse（非排他的、コメントなし）にしています。

このメソッドは、正常にファイルへ書き込んだバイト数を整数で返しますが、書き込みに失敗した場合はfalseを返します。サンプルコードでは、この戻り値を確認することで処理の成否を判断し、結果に応じて適切なメッセージを出力しています。これにより、XMLの書式に依存しない標準的なXMLデータとしてファイルを生成し、共有や比較に活用することが可能になります。