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

Copy
1<?php
2
3/**
4 * PHP DOM extensionの例：XMLの正規化（C14N）をファイルに書き出すデモンストレーション。
5 *
6 * このコードは、XMLドキュメントを正規化し、その結果を指定されたファイルに書き出す
7 * `C14NFile`メソッドの使用方法を示しています。
8 *
9 * 注意点:
10 * 提供されたリファレンス情報では「所属クラス: DOMNotation」と指定されていますが、
11 * 標準のPHP DOM拡張において、XML正規化を行う`C14NFile`メソッドは
12 * `DOMDocument`クラスに属しています。`DOMNotation`オブジェクトはDTDの記法を表し、
13 * ドキュメントレベルの正規化操作は行いません。
14 *
15 * そのため、このサンプルコードでは、提供されたメソッドシグネチャ（引数と戻り値）に
16 * 合致し、かつPHPで実際に機能する`DOMDocument::C14NFile`メソッドを使用しています。
17 * これにより、システムエンジニアを目指す初心者の方にも、正確で動作するC14Nの例を提供します。
18 */
19function demonstrateC14NFile(): void
20{
21    // 1. サンプルとなるXMLドキュメントを作成します。
22    //    C14Nの動作（コメントの削除、空白の正規化など）を示すため、
23    //    コメントや名前空間、余分な空白を含むシンプルなXMLを使用します。
24    $xmlString = <<<XML
25<?xml version="1.0" encoding="UTF-8"?>
26<root xmlns:my="http://example.com/ns">
27    <!-- これは正規化によって削除されるコメントです -->
28    <element id="1">
29        Hello
30        <child attr="value"/>
31    </element>
32    <my:other_element>World</my:other_element>
33</root>
34XML;
35
36    // 2. XMLをDOMDocumentオブジェクトにロードします。
37    $dom = new DOMDocument('1.0', 'UTF-8');
38    // `preserveWhiteSpace` を `false` に設定することで、C14Nの出力が一貫しやすくなります。
39    $dom->preserveWhiteSpace = false;
40    // XML文字列をDOMDocumentにロードします。
41    $dom->loadXML($xmlString);
42
43    // 3. 正規化されたXMLを書き出すための一時ファイルパスを定義します。
44    $outputFile = __DIR__ . '/canonicalized_output.xml';
45
46    // 4. XMLを正規化し、指定されたファイルに書き出します。
47    //    引数の定義: string $uri, bool $exclusive = false, bool $withComments = false, ?array $xpath = null, ?array $nsPrefixes = null
48    //    ここでは、最も基本的なC14N形式（排他的C14Nではない、コメントを含まない）で実行します。
49    $success = $dom->C14NFile(
50        $outputFile,        // $uri: 正規化されたXMLを書き出すファイルパス
51        false,              // $exclusive: 排他的C14Nを使用しない（デフォルトのC14N 1.0）
52        false,              // $withComments: コメントを正規化された出力に含めない
53        null,               // $xpath: 特定のノードセットに限定しない（ドキュメント全体を対象）
54        null                // $nsPrefixes: 特定の名前空間プレフィックスに限定しない
55    );
56
57    // 5. 正規化の成功/失敗をチェックし、結果を表示します。
58    if ($success) {
59        echo "XMLは正常に正規化され、ファイルに書き込まれました: {$outputFile}\n";
60        echo "\n--- canonicalized_output.xml の内容 ---\n";
61        echo file_get_contents($outputFile);
62        echo "---------------------------------------\n";
63    } else {
64        echo "XMLの正規化に失敗しました。\n";
65    }
66
67    // 6. 生成された一時ファイルをクリーンアップします。
68    if (file_exists($outputFile)) {
69        unlink($outputFile);
70        echo "\n{$outputFile} をクリーンアップしました。\n";
71    }
72}
73
74// 上記のデモンストレーション関数を実行します。
75demonstrateC14NFile();

PHPのDOMDocument::C14NFileメソッドは、XMLドキュメントを正規化し、その結果を指定されたファイルに書き出すために使用されます。正規化（C14N）とは、XMLの論理的な内容を変えずに、その物理的な表現を標準的な形式に変換するプロセスです。これにより、異なるXMLドキュメントが論理的に同じであるかどうかの比較が容易になります。

提供されたリファレンス情報では「DOMNotation」に属するとされていますが、実際にはDOMDocumentクラスのメソッドです。サンプルコードは、まずXML文字列をDOMDocumentオブジェクトとしてロードし、その後C14NFileメソッドを使って正規化されたXMLを「canonicalized_output.xml」というファイルに保存する一連の流れを示しています。

このメソッドは、第一引数$uriで出力先のファイルパスを指定します。$exclusiveをtrueに設定すると排他的C14Nが適用され、$withCommentsをtrueに設定するとコメントが正規化された出力に含まれます。$xpathや$nsPrefixesを使えば、ドキュメント全体ではなく特定のノードセットや名前空間に限定した正規化も可能です。メソッドは処理が成功すればtrueを、失敗すればfalseを返します。この機能は、XMLのデジタル署名や比較など、XMLの厳密な同一性を保証する必要がある場面で特に役立ちます。

Copy
1<?php
2
3/**
4 * XMLドキュメントを正規化（Canonicalization）し、指定されたファイルに保存します。
5 *
6 * この関数は、XMLドキュメントのDOM表現に対してC14NFileメソッドを呼び出します。
7 * C14N (Canonical XML) は、XMLドキュメントを比較可能で一貫性のある形式に変換する標準です。
8 * DOMDocumentクラスはDOMNodeを継承しているため、DOMNode::C14NFileメソッドを使用できます。
9 *
10 * @param string $xmlContent 正規化するXML文字列。
11 * @param string $outputPath 正規化されたXMLを保存するファイルのパス。
12 * @param bool $exclusive 排他的C14N (Exclusive Canonicalization) を使用するかどうか。
13 *                         false の場合、標準C14Nを使用します。
14 *                         デフォルトは false。
15 * @param bool $withComments コメントノードを正規化された出力に含めるかどうか。
16 *                            デフォルトは false。
17 * @param ?array $xpath XPath式に一致するノードのみを対象とするための配列。
18 *                       null の場合、ドキュメント全体を対象とします。デフォルトは null。
19 * @param ?array $nsPrefixes XPathと組み合わせて、特定の名前空間プレフィックスの宣言を含めるための配列。
20 *                            null の場合、デフォルトの動作を使用します。デフォルトは null。
21 * @return bool 正規化とファイルへの保存が成功した場合は true、それ以外は false。
22 */
23function generateCanonicalXmlFile(
24    string $xmlContent,
25    string $outputPath,
26    bool $exclusive = false,
27    bool $withComments = false,
28    ?array $xpath = null,
29    ?array $nsPrefixes = null
30): bool {
31    // 新しいDOMDocumentオブジェクトを作成
32    $dom = new DOMDocument('1.0', 'UTF-8');
33    // エラーハンドリングを強化するため、libxmlエラーを抑制し、後で取得します。
34    libxml_use_internal_errors(true);
35
36    // XML文字列をDOMオブジェクトにロード
37    if (!$dom->loadXML($xmlContent)) {
38        // XMLロード失敗時のエラーメッセージを表示
39        echo "エラー: XMLのロードに失敗しました。\n";
40        foreach (libxml_get_errors() as $error) {
41            echo "  " . $error->message;
42        }
43        libxml_clear_errors(); // エラーをクリア
44        return false;
45    }
46    libxml_clear_errors(); // 成功した場合もエラーをクリア
47
48    // XMLを正規化し、指定されたファイルに保存
49    // DOMDocumentはDOMNodeを継承しており、C14NFileメソッドはDOMNodeのメソッドです。
50    // 提供されたリファレンスの引数リストと一致します。
51    $success = $dom->C14NFile($outputPath, $exclusive, $withComments, $xpath, $nsPrefixes);
52
53    if ($success) {
54        echo "正規化されたXMLがファイル '{$outputPath}' に正常に保存されました。\n";
55        return true;
56    } else {
57        echo "エラー: XMLの正規化とファイルへの保存に失敗しました。\n";
58        return false;
59    }
60}
61
62// --- サンプルコードの実行 ---
63
64// 正規化するXMLコンテンツの例
65$sampleXml = <<<XML
66<?xml version="1.0" encoding="UTF-8"?>
67<root xmlns:ns="http://example.com/ns">
68    <!-- これはコメントです -->
69    <element attribute="value">
70        <child>テキストコンテンツ</child>
71    </element>
72    <ns:otherElement/>
73</root>
74XML;
75
76// 一時ファイルパスを生成 (システムの一時ディレクトリを使用)
77$outputFileBase = sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'canonical_output_';
78
79echo "--- 通常の正規化（コメントなし） ---\n";
80$outputFileDefault = $outputFileBase . 'default.xml';
81// デフォルトの正規化を実行（排他的C14Nなし、コメントなし）
82if (generateCanonicalXmlFile($sampleXml, $outputFileDefault)) {
83    echo "出力内容:\n";
84    echo htmlspecialchars(file_get_contents($outputFileDefault)) . "\n\n";
85    unlink($outputFileDefault); // 生成したファイルを削除
86}
87
88echo "--- コメントを含む正規化 ---\n";
89$outputFileWithComments = $outputFileBase . 'with_comments.xml';
90// コメントを含む正規化を実行
91if (generateCanonicalXmlFile($sampleXml, $outputFileWithComments, false, true)) {
92    echo "出力内容:\n";
93    echo htmlspecialchars(file_get_contents($outputFileWithComments)) . "\n\n";
94    unlink($outputFileWithComments); // 生成したファイルを削除
95}
96
97echo "--- 排他的正規化（コメントなし） ---\n";
98$outputFileExclusive = $outputFileBase . 'exclusive.xml';
99// 排他的C14Nを実行（コメントなし）
100// 排他的C14Nでは、名前空間の宣言がルート要素ではなく、それを参照する要素に直接記述されることがあります。
101// また、不要な名前空間宣言が省略されることがあります。
102if (generateCanonicalXmlFile($sampleXml, $outputFileExclusive, true, false)) {
103    echo "出力内容:\n";
104    echo htmlspecialchars(file_get_contents($outputFileExclusive)) . "\n\n";
105    unlink($outputFileExclusive); // 生成したファイルを削除
106}

PHP 8のDOMNotationクラスに属するとされるC14NFileメソッドは、XMLドキュメントをCanonical XML（C14N）と呼ばれる標準形式で正規化し、その結果を指定したファイルに保存する機能を提供します。C14Nとは、XMLドキュメントの内容に意味的な変更を加えることなく、比較可能で一貫性のある形式に変換するための標準です。この機能は、XMLドキュメントの同一性を比較したり、署名などで利用したりする場合に役立ちます。

このメソッドは、XMLドキュメントのDOM表現を扱うDOMDocumentクラスのオブジェクトから呼び出すことができます。これはDOMDocumentがDOMNodeを継承しており、C14NFileメソッドはDOMNodeのメソッドとして提供されているためです。

引数には、まず正規化されたXMLを保存するファイルパスを$uriとして指定します。$exclusiveをtrueにすると排他的C14Nが適用され、名前空間の宣言方法が通常と異なります。$withCommentsは、XML内のコメントノードを正規化された出力に含めるかどうかをtrueまたはfalseで指定します。$xpathや$nsPrefixesはオプションで、ドキュメント全体ではなく、XPath式に一致する特定のノードだけを対象としたり、特定の名前空間プレフィックスの宣言を含めたりする場合に利用します。

このメソッドは、正規化とファイルへの保存処理が成功した場合はtrueを、何らかの理由で失敗した場合はfalseを戻り値として返します。サンプルコードでは、様々なオプションでXMLを正規化し、ファイルに保存する具体的な手順を示しており、出力内容から正規化の違いを確認できます。