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

Copy
1<?php
2
3/**
4 * Dom\Element::C14NFile メソッドの使用例を示します。
5 * 指定されたXML要素をXML正規化 (C14N) し、その結果を指定されたファイルに保存します。
6 *
7 * @return void
8 */
9function demonstrateDomElementC14NFile(): void
10{
11    // DOMDocument オブジェクトを作成します。
12    $dom = new DOMDocument('1.0', 'UTF-8');
13    // XMLの空白文字の扱いはC14Nの結果に影響することがあるため、
14    // 通常はホワイトスペースを保持しない設定にしておくと、予測しやすい動作になります。
15    $dom->preserveWhiteSpace = false;
16    // 出力フォーマットを整形しますが、C14Nの最終的な結果はC14Nのルールに従います。
17    $dom->formatOutput = true;
18
19    // サンプルとなるXML文字列をロードします。
20    // XML正規化は、異なるXML表現でも同じ論理的内容を持つものを同一とみなすための標準化プロセスです。
21    $xmlString = <<<XML
22<root attr1="value1">
23    <element1 id="a">
24        <subelement1>テキスト1</subelement1>
25    </element1>
26    <element2 id="b">
27        <!-- これはXMLコメントです -->
28        <subelement2>テキスト2</subelement2>
29    </element2>
30</root>
31XML;
32
33    if (!$dom->loadXML($xmlString)) {
34        echo "エラー: XML文字列のロードに失敗しました。\n";
35        return;
36    }
37
38    // Dom\Element オブジェクトを取得します。
39    // C14NFile メソッドは Dom\Element クラスのメソッドであるため、
40    // XMLドキュメントから特定の要素を選択する必要があります。
41    // ここではルート要素 (<root>) を対象とします。
42    $targetElement = $dom->documentElement;
43
44    if (!$targetElement) {
45        echo "エラー: 対象となるルート要素が見つかりませんでした。\n";
46        return;
47    }
48
49    // 正規化されたXMLを保存する一時ファイルパスを生成します。
50    // sys_get_temp_dir() は、システムの一時ディレクトリのパスを返します。
51    $outputFilePath = sys_get_temp_dir() . '/dom_element_c14n_output.xml';
52
53    echo "--- オリジナルXML ---" . PHP_EOL;
54    echo $dom->saveXML() . PHP_EOL;
55    echo "--------------------" . PHP_EOL;
56
57    // Dom\Element::C14NFile メソッドを使用して要素をXML正規化し、ファイルに保存します。
58    // 引数:
59    // 1. string $uri: 正規化されたXMLを保存するファイルのURI（パス）。
60    // 2. bool $exclusive: 排他的正規化を使用するかどうか (デフォルト: false)。
61    //    排他的正規化は、不要な名前空間宣言を抑制します。
62    // 3. bool $withComments: コメントを含めるかどうか (デフォルト: false)。
63    //    今回は false を指定し、コメントは出力に含めません。
64    // (以降の引数 $xpath, $nsPrefixes は、より高度なノードセット選択に使用され、ここでは使用しません。)
65    try {
66        // コメントを含めずに非排他的なXML正規化を行います。
67        $targetElement->C14NFile($outputFilePath, false, false);
68
69        echo "要素がXML正規化 (C14N) され、ファイルに保存されました: {$outputFilePath}\n";
70
71        // 保存されたファイルの内容を確認します。
72        echo "\n--- 正規化されたファイル内容 ---" . PHP_EOL;
73        // file_get_contents() でファイルの内容を読み込み、表示します。
74        echo file_get_contents($outputFilePath) . PHP_EOL;
75        echo "-----------------------------\n";
76
77    } catch (Throwable $e) {
78        // C14NFileの実行中にエラーが発生した場合、例外が捕捉されます。
79        echo "エラーが発生しました: " . $e->getMessage() . PHP_EOL;
80    } finally {
81        // スクリプトの終了時に、作成した一時ファイルをクリーンアップします。
82        if (file_exists($outputFilePath)) {
83            unlink($outputFilePath);
84            echo "一時ファイル '{$outputFilePath}' を削除しました。\n";
85        }
86    }
87}
88
89// 関数を実行して、Dom\Element::C14NFile の動作を確認します。
90demonstrateDomElementC14NFile();
91

PHPのDom\Element::C14NFileメソッドは、XMLドキュメント内の特定の要素をXML正規化（Canonical XML、C14N）し、その結果を指定されたファイルに保存するための機能です。XML正規化とは、空白文字や属性の順序、名前空間宣言など、異なる表現でも論理的に同一なXMLを、唯一の標準形式に変換するプロセスです。主にXML署名の検証や、XMLデータの比較において一貫性を保証するために利用されます。

このメソッドはDom\Elementクラスのインスタンスに対して呼び出され、ターゲットとなるXML要素に適用されます。

引数について、string $uriは正規化されたXMLを保存するファイルのパスを指定します。bool $exclusiveは排他的正規化を行うかどうか（デフォルトはfalse）、bool $withCommentsはXMLコメントを正規化結果に含めるかどうか（デフォルトはfalse）を制御します。後続の引数は、より高度なノードセット選択に用いられますが、通常は省略可能です。

このメソッドは処理が成功した場合、戻り値を返しません（void）。

サンプルコードでは、まずDOMDocumentにXML文字列をロードし、そのルート要素を操作対象として取得しています。次に、C14NFileメソッドを呼び出し、一時ファイルにコメントを含まない非排他的な形式で正規化されたXMLを保存します。そして、そのファイルの内容を表示することで正規化されたXML形式を確認し、最後に作成した一時ファイルを削除してクリーンアップを行っています。これにより、XMLデータの一貫した処理と永続化が可能となります。

Copy
1<?php
2
3/**
4 * 指定されたXML要素を正規化された形式 (Canonical XML) でファイルに保存します。
5 *
6 * この関数は、XMLドキュメントをロードし、特定のタグ名の要素を選択し、
7 * その要素の内容を Canonical XML (C14N) 形式で指定されたファイルに書き出します。
8 * これは、XMLデータの一部または全体を標準化された方法で「コピー」または「保存」する用途に適しています。
9 *
10 * @param string $xmlString XMLソース文字列。
11 * @param string $elementTagName 正規化して保存する要素のタグ名。
12 * @param string $outputUri 正規化されたXMLを書き込むファイルのURI（パス）。
13 * @param bool $exclusive 排他的C14Nを使用するかどうか (デフォルト: false)。
14 * @param bool $withComments コメントを含めるかどうか (デフォルト: false)。
15 * @return bool ファイルへの書き込みが成功した場合はtrue、それ以外はfalse。
16 */
17function exportCanonicalXmlElementToFile(
18    string $xmlString,
19    string $elementTagName,
20    string $outputUri,
21    bool $exclusive = false,
22    bool $withComments = false
23): bool {
24    // DOMDocumentインスタンスを作成し、XMLをロードします。
25    // PHP 8では、古いDOMクラス（DOMDocumentなど）は新しいDom名前空間のクラスを基盤としているため、
26    // Dom\ElementのメソッドをDOMElementインスタンスに対して呼び出すことができます。
27    $dom = new DOMDocument();
28    $dom->preserveWhiteSpace = false; // パース時に空白ノードを保持しない設定
29
30    // XML文字列のロードを試みます。
31    if (!$dom->loadXML($xmlString)) {
32        echo "エラー: XML文字列のロードに失敗しました。\n";
33        return false;
34    }
35
36    // 指定されたタグ名の要素コレクションを取得します。
37    // 例: 'item' や 'ex:item' のようなタグ名で要素を探します。
38    $elements = $dom->getElementsByTagName($elementTagName);
39
40    // 要素が全く見つからなかった場合のエラー処理。
41    if ($elements->count() === 0) {
42        echo "エラー: タグ名 '{$elementTagName}' の要素が見つかりませんでした。\n";
43        return false;
44    }
45
46    // 最初に見つかった要素を取得します。
47    // getElementsByTagNameはDOMNodeListを返し、その中にDOMElementインスタンスが含まれます。
48    $elementToC14N = $elements->item(0);
49
50    // 取得したノードがDom\Element（またはDOMElement）のインスタンスであることを確認します。
51    // PHP 8以降では、DOMElementはDom\Elementとして機能します。
52    if (!$elementToC14N instanceof Dom\Element) {
53        echo "エラー: 見つかったノードは Dom\\Element 型ではありませんでした。\n";
54        return false;
55    }
56
57    try {
58        // Dom\Element::C14NFile メソッドを呼び出し、正規化されたXMLをファイルに保存します。
59        // このメソッドは戻り値がないため、例外が発生しない限り成功とみなします。
60        $elementToC14N->C14NFile($outputUri, $exclusive, $withComments);
61        return true;
62    } catch (Throwable $e) {
63        // ファイルへの書き込み中にエラーが発生した場合の例外処理。
64        echo "エラー: 正規化されたXMLのファイル書き込みに失敗しました。詳細: " . $e->getMessage() . "\n";
65        return false;
66    }
67}
68
69// --- 使用例 ---
70
71// サンプルXMLデータ
72$sampleXml = <<<XML
73<?xml version="1.0" encoding="UTF-8"?>
74<root xmlns:ex="http://example.com/ns">
75    <!-- ルート要素のコメント -->
76    <ex:item id="1">
77        <name>Item A</name>
78        <description>This is item A.</description>
79    </ex:item>
80    <item id="2">
81        <name>Item B</name>
82        <!-- アイテムBのコメント -->
83        <description>This is item B.</description>
84    </item>
85</root>
86XML;
87
88// 例1: 名前空間プレフィックス付きの要素 ('ex:item') を選択し、コメントを含めて正規化し、ファイルに保存する。
89$outputFile1 = 'canonical_ex_item_with_comments.xml';
90$elementTagName1 = 'ex:item';
91
92echo "--- 例1: '{$elementTagName1}' 要素をコメント含みで正規化してファイル保存 ---\n";
93if (exportCanonicalXmlElementToFile($sampleXml, $elementTagName1, $outputFile1, false, true)) {
94    echo "成功: '{$outputFile1}' に正規化されたXMLがエクスポートされました。\n";
95    echo "内容:\n";
96    echo "---------------------------------------------------\n";
97    echo file_get_contents($outputFile1);
98    echo "\n---------------------------------------------------\n";
99} else {
100    echo "失敗: '{$outputFile1}' へのエクスポートに失敗しました。\n";
101}
102
103// 例2: 名前空間なしの要素 ('item') を選択し、コメントを含めずに正規化し、ファイルに保存する。
104$outputFile2 = 'canonical_item_no_comments.xml';
105$elementTagName2 = 'item';
106
107echo "\n--- 例2: '{$elementTagName2}' 要素をコメントなしで正規化してファイル保存 ---\n";
108if (exportCanonicalXmlElementToFile($sampleXml, $elementTagName2, $outputFile2, false, false)) {
109    echo "成功: '{$outputFile2}' に正規化されたXMLがエクスポートされました。\n";
110    echo "内容:\n";
111    echo "---------------------------------------------------\n";
112    echo file_get_contents($outputFile2);
113    echo "\n---------------------------------------------------\n";
114} else {
115    echo "失敗: '{$outputFile2}' へのエクスポートに失敗しました。\n";
116}
117
118// 生成された一時ファイルをクリーンアップしたい場合は、以下のコメントを解除してください。
119// unlink($outputFile1);
120// unlink($outputFile2);
121?>

PHPのDom\Element::C14NFileメソッドは、XMLドキュメント内の特定の要素を「Canonical XML (C14N)」という標準形式で指定されたファイルに保存するための機能です。Canonical XMLとは、XMLの書式や表現の揺らぎをなくし、常に同じXMLデータであれば同じ出力になる標準形式で、XMLデータの比較やデジタル署名などで利用されます。このメソッドを使用することで、XMLドキュメントから特定の要素を抽出し、標準化された方法でファイルに「コピー」または「保存」することができます。

引数$uriには、正規化されたXMLを書き出すファイルのパスを指定します。$exclusiveは、名前空間の扱い方について排他的な正規化を使用するかどうかを真偽値で設定します。$withCommentsは、正規化された出力にXMLコメントを含めるかどうかを真偽値で指定します。例えば、XMLデータの一部だけをコメントを含めずに別のファイルとして保存したい場合に役立ちます。

このメソッドは戻り値を返しません。そのため、ファイルの書き込みが成功したかどうかは、メソッドの実行中に例外が発生しなかったことで判断します。提供されたサンプルコードでは、まずXML文字列をロードし、特定のタグ名を持つ要素を見つけ出します。そして、その要素に対してC14NFileメソッドを呼び出すことで、正規化されたXMLコンテンツをファイルへ書き出しています。これにより、XMLデータから必要な部分を標準化し、効率的に保存する作業を行えます。