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

Copy
1<?php
2
3/**
4 * DOMElement::C14NFile メソッドのサンプルコード
5 * XMLドキュメントから特定の要素を正規化し、ファイルに出力します。
6 * C14N (Canonical XML) は、XMLの異なる表現形式を標準的な形式に変換するプロセスです。
7 * これにより、XMLデータの比較や署名の検証が容易になります。
8 */
9
10// 出力先のファイルパスを定義します。
11$outputFilePath = 'normalized_xml_output.xml';
12
13// サンプルXMLデータを定義します。
14// コメントや異なる属性の順序などが含まれています。
15$xmlString = <<<XML
16<root xmlns="http://example.com/ns1" xmlns:ex="http://example.com/ns2">
17    <!-- このコメントは正規化のオプションによって含まれたり除外されたりします -->
18    <child id="1" some-attr="value">
19        <grandchild ex:attr="another_value">Hello, C14N!</grandchild>
20    </child>
21    <child id="2"/>
22</root>
23XML;
24
25try {
26    // 新しい DOMDocument オブジェクトを作成します。
27    $dom = new DOMDocument();
28    // 整形時に空白を保持しないように設定します（C14Nには直接影響しませんが、一般的なDOM操作には有効です）。
29    $dom->preserveWhiteSpace = false;
30    // XML文字列をDOMDocumentに読み込みます。
31    $dom->loadXML($xmlString);
32
33    // ドキュメントのルート要素を取得します。
34    // C14NFileはDOMElementのメソッドなので、特定の要素に対して呼び出す必要があります。
35    $rootElement = $dom->documentElement;
36
37    if (!$rootElement) {
38        throw new Exception("XMLドキュメントにルート要素が見つかりません。");
39    }
40
41    echo "DOMElement::C14NFile メソッドを使用してXMLを正規化し、ファイルに書き込みます。\n";
42    echo "出力先ファイル: " . $outputFilePath . "\n";
43
44    // C14NFile メソッドを呼び出し、XMLを正規化してファイルに書き込みます。
45    // 引数:
46    // 1. $uri: 出力先のファイルパス (string)
47    // 2. $exclusive: 排他的正規化を行うか (bool, デフォルト: false)。ここでは通常の正規化を行います。
48    // 3. $with_comments: コメントを含めるか (bool, デフォルト: false)。ここではコメントを含めます。
49    $bytesWritten = $rootElement->C14NFile($outputFilePath, false, true);
50
51    if ($bytesWritten === false) {
52        echo "エラー: C14NFile メソッドの実行に失敗しました。\n";
53    } else {
54        echo "成功: " . $bytesWritten . " バイトがファイル '" . $outputFilePath . "' に書き込まれました。\n";
55
56        // 書き込まれたファイルの内容を表示して確認します。
57        echo "\n--- 書き込まれた正規化されたXMLの内容 ---\n";
58        echo file_get_contents($outputFilePath);
59        echo "\n----------------------------------------\n";
60    }
61} catch (Exception $e) {
62    // 例外が発生した場合、エラーメッセージを表示します。
63    echo "例外が発生しました: " . $e->getMessage() . "\n";
64} finally {
65    // 後処理として、生成されたファイルを削除します。
66    if (file_exists($outputFilePath)) {
67        if (unlink($outputFilePath)) {
68            echo "一時ファイル '" . $outputFilePath . "' を削除しました。\n";
69        } else {
70            echo "警告: 一時ファイル '" . $outputFilePath . "' の削除に失敗しました。\n";
71        }
72    }
73}

PHP 8のDOMElement::C14NFileメソッドは、XMLドキュメント内にある特定の要素をCanonical XML (C14N) 形式に正規化し、その結果をファイルに出力するために用いられます。C14Nとは、XMLの異なる表記方法を統一された標準形式に変換するプロセスで、XMLデータの信頼性の高い比較や、デジタル署名の検証を容易にする目的があります。このメソッドはDOMElementクラスのインスタンスに対して呼び出すため、XMLツリー内の任意の要素を対象にできます。

引数としては、正規化されたXMLを保存するファイルパスを文字列型で指定する$uriが必須です。また、排他的正規化を行うかを真偽値で指定する$exclusive（デフォルトはfalse）、コメントを含めるかを真偽値で指定する$with_comments（デフォルトはfalse）などのオプションも設定できます。このメソッドは、ファイルに書き込まれたバイト数を整数で返し、処理が失敗した場合にはfalseを返します。

提示されたサンプルコードでは、まず準備としてXML文字列をDOMDocumentオブジェクトに読み込み、ドキュメントのルート要素を取得しています。その後、取得したルート要素に対してC14NFileメソッドを呼び出し、正規化されたXMLを指定されたファイルパス（normalized_xml_output.xml）に出力しています。この例では、$with_comments引数をtrueに設定しているため、元のXMLに含まれるコメントも正規化後の出力ファイルに含まれます。処理の成功時には書き込まれたバイト数が表示され、さらにファイルのコンテンツを読み込んで、正規化されたXMLの内容を確認できるようになっています。

Copy
1<?php
2
3/**
4 * 指定されたXML文字列からDOMElementを取得し、その要素をXML正規化 (Canonicalization) してファイルに保存します。
5 *
6 * この関数は、XMLドキュメントの指定された要素を、標準的な形式（正規化された形式）に変換し、
7 * その結果を新しいファイルとして出力します。
8 * 主にXMLの署名や比較など、XMLの同一性を保証する必要がある場面で使用されます。
9 *
10 * @param string $xmlString 正規化するXMLデータを含む文字列。
11 * @param string $outputFilePath 正規化されたXMLを保存するファイルのフルパス。
12 * @return bool 正規化とファイルの保存が成功した場合は true、それ以外は false。
13 */
14function createCanonicalizedXmlFile(string $xmlString, string $outputFilePath): bool
15{
16    // DOMDocument オブジェクトを初期化します。
17    // これはXMLドキュメントをメモリ内で表現するためのクラスです。
18    $dom = new DOMDocument();
19
20    // XML文字列をDOMDocumentにロードします。
21    // 失敗した場合はエラーメッセージを表示し、falseを返します。
22    libxml_use_internal_errors(true); // XMLロード時の警告を抑制
23    if (!$dom->loadXML($xmlString)) {
24        $errors = libxml_get_errors();
25        foreach ($errors as $error) {
26            error_log("XMLロードエラー: " . $error->message);
27        }
28        libxml_clear_errors();
29        echo "エラー: 不正なXML文字列が指定されたか、ロードに失敗しました。\n";
30        return false;
31    }
32    libxml_use_internal_errors(false);
33
34    // ドキュメントのルート要素を取得します。
35    // DOMElement::C14NFile メソッドは DOMElement オブジェクトに対して呼び出す必要があります。
36    $rootElement = $dom->documentElement;
37
38    // ルート要素が存在しない場合（例: 空のXML文字列）はエラーを報告し、falseを返します。
39    if ($rootElement === null) {
40        echo "エラー: XMLドキュメントにルート要素がありません。\n";
41        return false;
42    }
43
44    // DOMElement::C14NFile メソッドを使用して、要素を正規化し、指定されたファイルに書き込みます。
45    // 第一引数: $uri (string) - 正規化されたXMLを保存するファイルのURI（パス）。
46    // 第二引数: $exclusive (bool) - 排他的正規化を行うか (通常は false で非排他的)。
47    // 第三引数: $with_comments (bool) - コメントを含めるか (通常は false で含めない)。
48    // 戻り値は書き込まれたバイト数（int）、または失敗した場合は false です。
49    $bytesWritten = $rootElement->C14NFile($outputFilePath, false, false);
50
51    // 書き込みが成功したかを確認します。
52    if ($bytesWritten === false) {
53        echo "エラー: XMLをファイル '{$outputFilePath}' に正規化して保存できませんでした。\n";
54        return false;
55    }
56
57    echo "XMLが正規化され、ファイルに保存されました: '{$outputFilePath}' ({$bytesWritten} バイト)\n";
58    return true;
59}
60
61// --- サンプル使用例 ---
62
63// 正規化する元のXMLデータ。
64// コメントや属性の順序、空白などが正規化プロセスで変更されることがあります。
65$originalXml = <<<XML
66<root  attrB="valueB"  attrA="valueA" >
67    <!-- このコメントは通常、正規化時に除外されます -->
68    <element id="1">
69        Hello
70    </element>
71    <element id="2" />
72</root>
73XML;
74
75// 正規化されたXMLを保存するファイルのパスを定義します。
76// __DIR__ は現在のスクリプトがあるディレクトリの絶対パスを返します。
77$outputFilename = 'canonicalized_output.xml';
78$outputPath = __DIR__ . '/' . $outputFilename;
79
80// 関数を呼び出してXML正規化を実行し、結果をファイルに保存します。
81if (createCanonicalizedXmlFile($originalXml, $outputPath)) {
82    echo "正規化されたXMLファイルを正常に作成しました。\n";
83    // 必要であれば、生成されたファイルの内容を表示して確認できます。
84    // echo "\n--- {$outputFilename} の内容 ---\n";
85    // echo file_get_contents($outputPath);
86    // echo "\n----------------------------\n";
87} else {
88    echo "正規化されたXMLファイルの作成に失敗しました。\n";
89}
90
91// 後処理: 生成されたファイルをクリーンアップします (単体動作のコードとして推奨されます)。
92if (file_exists($outputPath)) {
93    if (unlink($outputPath)) {
94        echo "出力ファイル '{$outputPath}' を削除しました。\n";
95    } else {
96        echo "出力ファイル '{$outputPath}' の削除に失敗しました。\n";
97    }
98}
99
100?>

DOMElement::C14NFileは、PHPのDOM拡張機能で提供されるメソッドで、XMLドキュメントの特定の要素を「XML正規化（Canonicalization）」し、その結果を指定されたファイルに保存します。XML正規化とは、XMLの構造や内容を標準的な形式に変換する処理です。これにより、属性の順序や空白文字、エンコーディングなどの違いを吸収し、内容が同じXMLであれば常に同じバイト列として表現できるようになります。この機能は、XMLのデジタル署名や比較など、XMLデータの同一性を厳密に保証する必要がある場面で非常に重要です。

このサンプルコードでは、まず与えられたXML文字列をDOMDocumentオブジェクトとしてメモリに読み込み、ドキュメントのルート要素を取得しています。次に、このルート要素に対してC14NFileメソッドを呼び出します。第一引数には、正規化されたXMLを保存するファイルのパス（URI）を指定します。第二引数と第三引数は、それぞれ排他的正規化を行うか、コメントを含めるかをブール値で設定できますが、この例では両方ともfalseを指定し、コメントを含まない非排他的正規化を行っています。このメソッドは、ファイルに書き込まれたバイト数（整数値）を成功時に返し、処理が失敗した場合はfalseを返します。サンプルコードでは、この戻り値を確認することで、XMLの正規化とファイルへの保存が成功したかどうかを判断し、適切なメッセージを表示しています。