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

Copy
1<?php
2
3/**
4 * PHP DOM拡張機能によるXML正規化 (C14N) のデモンストレーション。
5 * C14NFileメソッドを使用してXMLドキュメントを正規化し、ファイルに保存します。
6 *
7 * 注: 提供されたリファレンスでは'Dom\Attr::C14NFile'とありましたが、
8 * 標準のPHP 8では、C14NFileはDOMDocumentまたはDOMNodeのメソッドであり、
9 * ドキュメント全体の正規化に使用されます。このコードはDOMDocument::C14NFileを例示します。
10 */
11function demonstrateC14NFile(): void
12{
13    // 1. DOMDocumentインスタンスを生成し、XML構造を構築します。
14    //    これはXMLドキュメント全体を表します。
15    $dom = new DOMDocument('1.0', 'UTF-8');
16    $dom->formatOutput = true; // 出力を整形（デバッグ用）
17
18    // ルート要素を作成し、ドキュメントに追加
19    $root = $dom->createElement('root');
20    $dom->appendChild($root);
21
22    // 子要素を作成し、属性と内容を追加
23    $child = $dom->createElement('child', 'Content for canonicalization');
24    $child->setAttribute('id', 'unique-id-1');
25    $root->appendChild($child);
26
27    // コメントは`$with_comments = true`の場合に正規化出力に含まれます。
28    $comment = $dom->createComment(' This is a sample comment ');
29    $root->appendChild($comment);
30
31    // 2. 正規化されたXMLを保存するための一時ファイルパスを設定します。
32    $outputFilePath = sys_get_temp_dir() . '/canonical_output_php8.xml';
33
34    echo "--- オリジナルXML ---" . PHP_EOL;
35    echo $dom->saveXML() . PHP_EOL . PHP_EOL;
36
37    // 3. C14NFileメソッドを呼び出し、XMLドキュメントを正規化してファイルに保存します。
38    //    引数:
39    //    - $uri: 正規化されたXMLを書き込むファイルパス。
40    //    - $exclusive: 排他的正規化を使用するかどうか (通常はfalse)。
41    //    - $with_comments: コメントを正規化された出力に含めるかどうか (今回はtrueに設定)。
42    //    - $xpath: (オプション) 特定のノードセットのみを正規化するためのXPath式配列。
43    //    - $ns_prefixes: (オプション) 排他的正規化時の名前空間プレフィックス配列。
44    $bytesWritten = $dom->C14NFile(
45        $outputFilePath,
46        false, // 排他的正規化は行わない (Canonical XML 1.0)
47        true   // コメントを含めて正規化する
48    );
49
50    // 4. C14NFileメソッドの戻り値をチェックし、結果を表示します。
51    if ($bytesWritten !== false) {
52        echo "XMLが正規化され、ファイルに保存されました。" . PHP_EOL;
53        echo "パス: " . $outputFilePath . PHP_EOL;
54        echo "書き込まれたバイト数: " . $bytesWritten . PHP_EOL . PHP_EOL;
55
56        echo "--- 正規化されたXMLの内容 ---" . PHP_EOL;
57        echo file_get_contents($outputFilePath) . PHP_EOL;
58
59        // 5. デモンストレーション後に作成した一時ファイルを削除します。
60        unlink($outputFilePath);
61    } else {
62        echo "XMLの正規化とファイルへの保存に失敗しました。" . PHP_EOL;
63    }
64}
65
66// デモンストレーション関数を実行します。
67demonstrateC14NFile();
68

PHPのDOMDocument::C14NFileメソッドは、XMLドキュメントの内容を「正規化」し、その結果を指定したファイルに保存するための機能です。XMLの正規化とは、要素や属性の順序、名前空間の記述方法、空白文字の扱いなど、表現上の違いを吸収して常に同じバイト列となるように変換することです。これにより、異なる環境で作成されたXMLでも、その内容が本質的に同じであれば、常に同じ正規化された結果が得られ、XMLのデジタル署名など、一貫性が求められる場面で重要になります。

このサンプルコードでは、まずPHPのDOMDocumentクラスで簡単なXML構造を構築します。次に、C14NFileメソッドを呼び出し、構築したXMLドキュメントを正規化して指定されたファイルパス（$uri）に書き出しています。引数$exclusiveで排他的正規化を行うか、$with_commentsでコメントを正規化された出力に含めるかを指定できます。メソッドが成功すると、書き込まれたバイト数（int）が返され、ファイルに内容が保存されます。失敗した場合はfalseが返されます。コード実行後、正規化されたXMLファイルが作成され、その内容を確認することができます。

Copy
1<?php
2
3/**
4 * Dom\Attr::C14NFile メソッドを使用して、指定されたXML属性の正規化された内容をファイルに保存します。
5 *
6 * この関数は、システムエンジニアを目指す初心者が、特定のXMLノード（ここでは属性）を
7 * 標準的な形式（正規化）でファイルに出力する方法を理解するのに役立ちます。
8 * キーワード「cp」（copy/保存）に関連付け、正規化結果をファイルに「保存」する例としています。
9 *
10 * @param string $xmlString 正規化する属性を含むXML文字列。
11 * @param string $attributeName 正規化する属性の名前。
12 * @param string $outputFilePath 正規化結果を書き込むファイルのパス。
13 * @return bool 処理が成功した場合は true、失敗した場合は false。
14 */
15function saveNormalizedAttributeToFile(string $xmlString, string $attributeName, string $outputFilePath): bool
16{
17    // DOMDocument オブジェクトを作成し、XML文字列を読み込みます。
18    // '1.0' はXMLのバージョン、'UTF-8' はエンコーディングを指定します。
19    $dom = new DOMDocument('1.0', 'UTF-8');
20    
21    // XMLの読み込みが成功したかを確認します。
22    if (!$dom->loadXML($xmlString)) {
23        echo "エラー: XML文字列の読み込みに失敗しました。\n";
24        return false;
25    }
26
27    // ドキュメントのルート要素を取得します。
28    // $dom->documentElement は、DOMツリーの最上位要素（通常はXMLのルートタグ）を返します。
29    $rootElement = $dom->documentElement;
30
31    if ($rootElement instanceof DOMElement) {
32        // 指定された名前の属性ノードを取得します。
33        // getAttributeNode() は DOMAttr オブジェクトを返します。
34        $attrNode = $rootElement->getAttributeNode($attributeName);
35
36        if ($attrNode instanceof DOMAttr) {
37            // Dom\Attr::C14NFile メソッドを呼び出し、属性の正規化された内容をファイルに書き出します。
38            // C14NFile は、XMLの正規化（Canonicalization）された文字列を指定のファイルに書き込む機能です。
39            //
40            // - 第1引数 ($outputFilePath): 正規化された内容の出力先ファイルパス。
41            // - 第2引数 (false): 排他的正規化を使用しない（非排他的正規化）。
42            // - 第3引数 (false): コメントを含めない。
43            $bytesWritten = $attrNode->C14NFile(
44                $outputFilePath,
45                false, // exclusive: 排他的正規化を使用しない
46                false  // with_comments: コメントを含めない
47            );
48
49            if ($bytesWritten !== false) {
50                echo "INFO: 属性 '" . $attributeName . "' の正規化された内容をファイルに保存しました: " . $outputFilePath . "\n";
51                echo "INFO: 書き込まれたバイト数: " . $bytesWritten . " バイト。\n";
52                return true;
53            } else {
54                echo "エラー: ファイル '" . $outputFilePath . "' への書き込みに失敗しました。\n";
55                return false;
56            }
57        } else {
58            echo "エラー: XML内に属性 '" . $attributeName . "' が見つかりませんでした。\n";
59            return false;
60        }
61    } else {
62        echo "エラー: XMLのルート要素が見つかりませんでした。\n";
63        return false;
64    }
65}
66
67// --- 以下はサンプルコードの実行部分です。この部分が実際に上記の関数を呼び出します。 ---
68
69// 正規化する属性を含むサンプルXML文字列を定義します。
70$sampleXml = '<root attribute="exampleValue" other="value"><child/></root>';
71// 正規化対象の属性名を指定します。
72$targetAttribute = 'attribute';
73// 正規化結果を書き出すファイルパスを指定します。
74$outputFile = 'normalized_attribute.xml';
75
76// 上で定義した関数を呼び出して、XML属性の正規化とファイルへの保存処理を実行します。
77$success = saveNormalizedAttributeToFile($sampleXml, $targetAttribute, $outputFile);
78
79// 処理が成功した場合は、出力ファイルの内容を表示して確認します。
80if ($success) {
81    echo "\n--- 出力ファイルの内容（" . $outputFile . "）---\n";
82    if (file_exists($outputFile)) {
83        // file_get_contents でファイルの内容を読み込み、そのまま表示します。
84        // この例では、出力ファイルには " attribute=\"exampleValue\"" のような文字列が書き込まれます。
85        echo file_get_contents($outputFile) . "\n";
86    } else {
87        echo "エラー: 出力ファイルが見つかりません。処理が途中で失敗した可能性があります。\n";
88    }
89}
90
91// クリーンアップ: このサンプルで作成した一時ファイルを削除します。
92// ファイルシステムをきれいに保つために、不要になったファイルを削除することは良い習慣です。
93if (file_exists($outputFile)) {
94    unlink($outputFile);
95    echo "\nINFO: 一時ファイル '" . $outputFile . "' を削除しました。\n";
96}
97

PHPのDom\Attr::C14NFileメソッドは、XMLドキュメント内の特定の属性（attribute）を「正規化」し、その結果をファイルに保存する機能を提供します。システムエンジニアを目指す方にとって、XMLデータを標準的な形式で扱ったり、特定の要素の内容をファイルとして保存する際に役立ちます。「cp」（コピー）のキーワードが示すように、属性の正規化結果をファイルへ書き出すイメージです。

このメソッドは、Dom\Attrオブジェクト、つまりXML要素に付加された属性ノードに対して呼び出されます。XMLの正規化とは、同じ内容のXMLであっても、書式や空白文字の違いなどによって物理的に異なる表現になるのを防ぎ、統一された標準形式に変換するプロセスです。これにより、XMLデータの正確な比較や処理が容易になります。

C14NFileメソッドは第一引数に正規化結果を保存するファイルのパス（string $uri）を指定します。これにより、属性の正規化された内容が指定されたファイルに書き込まれます。第二引数bool $exclusiveは排他的正規化を使うかどうか、第三引数bool $with_commentsはコメントを含めるかどうかを決定し、通常はfalseを指定して非排他的でコメントを含まない形式で出力します。

メソッドが成功すると、ファイルに書き込まれたバイト数（int）が返されます。書き込みに失敗した場合はfalseが返されるため、処理の成否を確認できます。サンプルコードでは、DOMDocumentでXMLを読み込み、特定の属性ノードを取得した後、このC14NFileメソッドを呼び出して正規化された属性値をファイルに保存する手順を示しています。これにより、XML属性の標準化された内容を簡単にファイルに出力できます。