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

Copy
1<?php
2
3/**
4 * PHP DOMDocument::C14NFile メソッドの利用例
5 *
6 * この関数は、XMLドキュメントを作成し、それを標準化（canonicalization）してファイルに保存する方法を示します。
7 * 標準化とは、XMLの論理的な内容を保持しつつ、構文上のバリエーション（属性の順序、空白、エンコーディングなど）を排除して
8 * 一意な表現に変換するプロセスです。これは、XML署名や比較において重要です。
9 *
10 * 注意: 提供されたリファレンス情報の「所属クラス: Dom\CharacterData」は、PHPのDOM拡張における
11 * C14NFile メソッドの実際の所属クラスとは異なります。C14NFile メソッドは、主に DOMDocument
12 * および DOMNode クラスに存在します。ここでは、ドキュメント全体を標準化するために DOMDocument を使用します。
13 */
14function demonstrateXmlC14NFile(): void
15{
16    // 1. 新しいDOMDocumentインスタンスを作成
17    $dom = new DOMDocument('1.0', 'UTF-8');
18    $dom->formatOutput = true; // 出力時に整形を行う (C14Nには影響しないが、元のXMLを見やすくするため)
19
20    // 2. XMLドキュメントの構造を構築
21    $root = $dom->createElement('root');
22    $dom->appendChild($root);
23
24    $elementA = $dom->createElement('elementA', 'Hello World!');
25    $elementA->setAttribute('id', 'item1');
26    $root->appendChild($elementA);
27
28    // コメントは通常、標準化プロセスで無視されることが多いが、C14NFileの引数で含めることができる
29    $comment = $dom->createComment(' This is a comment ');
30    $root->appendChild($comment);
31
32    $elementB = $dom->createElement('elementB', 'PHP C14N Example');
33    $elementB->setAttribute('name', 'example');
34    $root->appendChild($elementB);
35
36    // 3. 元のXMLを一時ファイルに保存 (標準化前と比較のため)
37    $originalXmlFile = 'original_document.xml';
38    $dom->save($originalXmlFile);
39    echo "オリジナルXMLが次のファイルに保存されました: " . realpath($originalXmlFile) . "\n";
40    echo "内容:\n" . file_get_contents($originalXmlFile) . "\n\n";
41
42    // 4. 標準化されたXMLの出力ファイルパスを定義
43    $canonicalizedFile = 'canonicalized_document.xml';
44
45    // 5. C14NFile メソッドを使用してXMLを標準化し、ファイルに保存
46    // 引数:
47    //   $uri: 出力先のファイルパス
48    //   $exclusive: 排他的標準化を使用するか (false = 非排他的)
49    //   $with_comments: コメントを標準化に含めるか (true = 含める)
50    //   $xpath: (オプション) 特定のノードセットのみを標準化する場合のXPath配列
51    //   $ns_prefixes: (オプション) 名前空間プレフィックスの配列
52    $bytesWritten = $dom->C14NFile(
53        $canonicalizedFile,
54        false, // 排他的標準化ではない
55        true   // コメントを含める
56    );
57
58    if ($bytesWritten !== false) {
59        echo "XMLが正常に標準化され、次のファイルに保存されました: " . realpath($canonicalizedFile) . "\n";
60        echo "書き込まれたバイト数: " . $bytesWritten . "\n";
61        echo "標準化されたXMLの内容:\n" . file_get_contents($canonicalizedFile) . "\n";
62    } else {
63        echo "エラー: XMLの標準化に失敗しました。\n";
64    }
65
66    // 6. クリーンアップ: 作成した一時ファイルを削除
67    if (file_exists($originalXmlFile)) {
68        unlink($originalXmlFile);
69    }
70    if (file_exists($canonicalizedFile)) {
71        unlink($canonicalizedFile);
72    }
73}
74
75// 関数を実行
76demonstrateXmlC14NFile();

PHPのDOMDocument::C14NFileメソッドは、XMLドキュメントを「標準化（Canonicalization）」し、その結果をファイルに保存する際に利用されます。XMLの標準化とは、XMLの論理的な内容は変えずに、属性の順序、空白文字、エンコーディングといった構文上の違いを吸収し、常に一意な表現に変換するプロセスです。これは、XMLの電子署名や、二つのXMLドキュメントが論理的に等しいかを比較する際に非常に重要な役割を果たします。

このサンプルコードでは、まずPHPのDOMDocumentクラスを用いて基本的なXMLドキュメントを構築し、それを一時ファイルとして保存します。その後、C14NFileメソッドを呼び出し、構築したXMLを標準化して別のファイルに保存する一連の流れを示しています。第一引数$uriには標準化後のXMLを保存するファイルパスを指定します。$exclusive引数で排他的標準化を行うか、$with_comments引数でXML内のコメントを標準化に含めるかを制御できます。メソッドは、ファイルに書き込まれたバイト数を整数値で返し、標準化に失敗した場合はfalseを返します。これにより、XMLが正しく標準化され、指定されたファイルに保存されたことを確認できます。

Copy
1<?php
2
3/**
4 * Dom\CharacterData::C14NFile メソッドを使用して、DOMTextノードの内容をファイルに正規化して書き出す関数。
5 *
6 * システムエンジニアを目指す初心者向けに、Dom\CharacterDataクラスに属するメソッドの基本的な使用法を示します。
7 * キーワード "php cp" に関連付けて、データの「コピー」（この場合は正規化された形式での書き出し）を実演します。
8 */
9function writeCanonicalCharacterDataToFile(): void
10{
11    // 1. 新しいDOMDocumentを作成し、簡単なXML構造を構築します。
12    // Dom\CharacterDataは抽象クラスのため、その具象子であるDOMTextノードを使用します。
13    $dom = new DOMDocument('1.0', 'UTF-8');
14    $root = $dom->createElement('document');
15    $dom->appendChild($root);
16
17    $element = $dom->createElement('data');
18    $root->appendChild($element);
19
20    // DOMTextはDom\CharacterDataを継承しています。
21    $textNodeContent = 'これはテストのテキストデータです。';
22    $textNode = $dom->createTextNode($textNodeContent);
23    $element->appendChild($textNode);
24
25    // 2. 正規化された出力を保存するファイルパスを定義します。
26    $outputFilePath = 'canonical_character_data.txt';
27
28    echo "テキストノードを正規化し、'{$outputFilePath}' に書き込みを試みます...\n";
29
30    // 3. Dom\CharacterData::C14NFile メソッドを呼び出します。
31    // $textNodeはDom\CharacterDataのインスタンス（DOMText）です。
32    // 引数はデフォルト値を使用します。テキストノードの場合、排他的正規化やコメントの有無は出力に影響しません。
33    $bytesWritten = $textNode->C14NFile(
34        $outputFilePath,
35        false, // $exclusive: 排他的正規化を使用しない
36        false  // $with_comments: コメントを含めない (テキストノードには関係なし)
37    );
38
39    if ($bytesWritten !== false) {
40        echo "成功: {$bytesWritten} バイトを '{$outputFilePath}' に書き込みました。\n";
41        echo "\n--- '{$outputFilePath}' の内容 ---\n";
42        echo file_get_contents($outputFilePath);
43        echo "\n-----------------------------------\n";
44    } else {
45        echo "エラー: '{$outputFilePath}' への書き込みに失敗しました。\n";
46    }
47
48    // 4. クリーンアップ: 生成されたファイルを削除します。
49    if (file_exists($outputFilePath)) {
50        unlink($outputFilePath);
51        echo "クリーンアップ: '{$outputFilePath}' を削除しました。\n";
52    }
53}
54
55// 関数を実行してデモンストレーションを開始します。
56writeCanonicalCharacterDataToFile();

このサンプルコードは、PHPのDOM拡張機能において、Dom\CharacterDataを継承するDOMTextノードのデータをファイルに正規化して書き出す方法を、システムエンジニアを目指す初心者向けに示しています。これは、あるデータを別の場所に「コピー」して保存する操作（キーワード「php cp」のように）と似た振る舞いをします。

コードではまず、新しいDOMDocumentを作成し、その中にテキストデータを含む簡単なXML構造を構築します。このテキストデータが、DOMTextノードとしてDom\CharacterDataのインスタンスとなり、処理の対象となります。

次に、このDOMTextノードに対してC14NFileメソッドを呼び出します。このメソッドは、ノードの内容をXML正規化された形式で、第一引数$uriで指定されたファイルパスに書き込みます。$exclusiveや$with_commentsといったオプション引数は、複雑なXMLドキュメント全体を正規化する際に効果を発揮しますが、テキストノードの書き出しではデフォルト値で問題なく動作します。

メソッドが成功すると、ファイルに書き込まれたバイト数が整数で返されます。失敗した場合はfalseが返されるため、戻り値を確認することで処理の成否を判断できます。この例では、書き込み後にファイルの内容を表示し、最後に作成されたファイルを削除してクリーンアップを行っています。これにより、特定のテキストデータを正規化された形式でファイルに安全に保存する基本的な手順を学ぶことができます。