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

Copy
1<?php
2
3// このサンプルコードは Dom\Comment::C14NFile メソッドの使用方法を示します。
4// XMLコメントノードを正規化（Canonicalization）し、その結果をファイルに書き込みます。
5
6// 出力するファイルパスを定義します。スクリプトが実行されているディレクトリにファイルを作成します。
7$outputFilePath = __DIR__ . '/c14n_comment_output.xml';
8
9try {
10    // Dom\Document の新しいインスタンスを作成します。
11    // PHP 8ではDom名前空間のクラスが推奨されます。
12    $dom = new Dom\Document('1.0', 'UTF-8');
13    $dom->formatOutput = true; // 出力されるXMLを見やすく整形します。
14
15    // ドキュメントにルート要素を追加します。
16    // C14NFileメソッドはノードに対して動作するため、DOM構造を形成する必要があります。
17    $root = $dom->createElement('root');
18    $dom->appendChild($root);
19
20    // 正規化したいXMLコメントを作成します。
21    // '&', '<', '>' のような特殊文字を含めて、正規化の効果を確認します。
22    $commentContent = "これはXMLコメントのサンプルです。特別な文字 &amp; < > も含みます。";
23    $commentNode = $dom->createComment($commentContent);
24
25    // 作成したコメントノードをルート要素に追加します。
26    $root->appendChild($commentNode);
27
28    echo "--- Dom\\Comment::C14NFile メソッドの実行 ---" . PHP_EOL;
29
30    // コメントノードに対して C14NFile メソッドを実行します。
31    // 引数:
32    // 1. $uri (string): 正規化されたXMLを書き込むファイルパス。
33    // 2. $exclusive (bool): 排他的なC14Nを使用するかどうか。falseで非排他的C14N（デフォルト）。
34    // 3. $with_comments (bool): コメントを含むC14Nを実行するかどうか。trueでコメントを含む（デフォルトはfalse）。
35    // 4. $xpath (array): XPath式で正規化するノードを絞り込む場合に使用（今回は省略）。
36    // 5. $ns_prefixes (array): 名前空間プレフィックスを定義する場合に使用（今回は省略）。
37    // 戻り値: 書き込まれたバイト数 (int) または失敗した場合に false。
38    $bytesWritten = $commentNode->C14NFile($outputFilePath, false, true);
39
40    if ($bytesWritten !== false) {
41        echo "C14NFile の実行に成功しました。{$bytesWritten} バイトが '{$outputFilePath}' に書き込まれました。" . PHP_EOL;
42
43        // 生成されたファイルの内容を読み込み、表示して結果を確認します。
44        if (file_exists($outputFilePath)) {
45            echo PHP_EOL . "--- 生成されたファイル内容 ---" . PHP_EOL;
46            echo file_get_contents($outputFilePath) . PHP_EOL;
47            echo "------------------------------" . PHP_EOL;
48        }
49    } else {
50        echo "C14NFile の実行に失敗しました。ファイルへの書き込み中にエラーが発生した可能性があります。" . PHP_EOL;
51    }
52
53} catch (Exception $e) {
54    // エラーが発生した場合、メッセージを出力します。
55    echo "エラーが発生しました: " . $e->getMessage() . PHP_EOL;
56} finally {
57    // クリーンアップ: このスクリプトによって生成された一時ファイルを削除します。
58    if (file_exists($outputFilePath)) {
59        unlink($outputFilePath);
60        echo "クリーンアップ: 生成されたファイル '{$outputFilePath}' を削除しました。" . PHP_EOL;
61    }
62}
63
64?>

このPHPサンプルコードは、XMLドキュメント内のコメントノードを標準形式に正規化（Canonicalization）し、その結果を指定のファイルに書き出すDom\Comment::C14NFileメソッドの使用方法を初心者向けに示しています。

コードではまず、Dom\Documentクラスのインスタンスを作成し、その中に正規化したいXMLコメントノードを追加します。このコメントノードには、特殊文字を含む文字列を設定しており、正規化によってこれらの文字がどのように処理されるかを確認できます。

次に、作成したコメントノードに対してC14NFileメソッドを呼び出します。このメソッドの最初の引数には、正規化されたXMLデータを保存するファイルのパスを指定します。ここでは、スクリプト実行ディレクトリにファイルが作成されます。三番目の引数$with_commentsをtrueに設定することで、コメント自体も正規化の対象となります。

メソッドが成功すると、ファイルに書き込まれたバイト数が整数で返され、指定されたファイルに正規化されたコメント内容が出力されます。失敗した場合はfalseが返されるため、戻り値を確認することで処理の成否を判断できます。コードの最後には、生成されたファイルを削除するクリーンアップ処理も含まれています。

Copy
1<?php
2
3/**
4 * この関数は、Dom\Comment::C14NFile メソッドを使用して、
5 * コメントノードの正規化された形式をファイルに保存する方法を示します。
6 *
7 * 正規化 (C14N) は、XMLドキュメントを一意の標準形式に変換するプロセスで、
8 * 特にデジタル署名で変更を検出するために使用されます。
9 * "php cp" のキーワードは、正規化されたコンテンツをファイルに「コピー」する
10 * という意味で関連しています。
11 *
12 * @param string $outputFilename 保存するファイルのパス。
13 */
14function saveCanonicalCommentToFile(string $outputFilename): void
15{
16    // Dom\Document オブジェクトを作成します。
17    // コメントノードは通常、このドキュメント内に作成されます。
18    $document = new Dom\Document();
19
20    // Dom\Comment ノードを作成します。
21    // 正規化ルールにより、コメントの内容内の前後の空白は通常トリムされます。
22    $commentContent = ' これは正規化されるサンプルコメントです。 ';
23    $commentNode = $document->createComment($commentContent);
24
25    echo "コメントノードの正規化された形式をファイル '{$outputFilename}' に保存しようとしています。\n";
26
27    // Dom\Comment オブジェクトの C14NFile メソッドを呼び出します。
28    // このメソッドは、ノードの正規化されたテキスト表現を指定されたファイルに書き込みます。
29    // 引数:
30    // 1. $uri: 出力ファイルのパス。
31    // 2. $exclusive: false は標準的な (非排他的) XML正規化を示します。
32    // 3. $with_comments: false は他のコメントを含めないことを示しますが、
33    //    このメソッドがコメントノード自体に直接呼び出されているため、
34    //    そのコメント自身のコンテンツは常に出力されます。
35    $bytesWritten = $commentNode->C14NFile($outputFilename, false, false);
36
37    if ($bytesWritten === false) {
38        echo "エラー: ファイル '{$outputFilename}' へのコメントの正規化に失敗しました。\n";
39    } else {
40        echo "コメントの正規化に成功し、{$bytesWritten} バイトが '{$outputFilename}' に書き込まれました。\n";
41
42        // 書き込まれたファイルの内容を確認します。
43        if (file_exists($outputFilename)) {
44            echo "ファイル '{$outputFilename}' の内容:\n";
45            echo file_get_contents($outputFilename) . "\n";
46
47            // 生成されたファイルをクリーンアップします。
48            unlink($outputFilename);
49            echo "ファイル '{$outputFilename}' をクリーンアップしました。\n";
50        }
51    }
52}
53
54// 出力ファイル名を定義します。
55$outputFileName = 'canonical_comment.xml';
56
57// 関数を実行してデモンストレーションします。
58saveCanonicalCommentToFile($outputFileName);
59
60?>

このサンプルコードは、PHPのDom\Comment::C14NFileメソッドを利用して、XMLコメントノードの正規化された形式をファイルに保存する方法を示しています。正規化（C14N）とは、XMLドキュメントの内容を一意の標準的な表現に変換するプロセスで、例えばデジタル署名で内容の改ざんを検出する際などに用いられます。「php cp」というキーワードは、正規化されたコメントのコンテンツをファイルに「コピー」して出力する、このメソッドの挙動と関連があります。

コードではまずDom\DocumentとDom\Commentノードを作成します。次に、このコメントノードのC14NFileメソッドを呼び出しています。このメソッドは、第一引数$uriで指定されたファイルパスに、コメントノードの正規化されたテキスト表現を書き込みます。第二引数$exclusiveは排他的正規化を行うかどうか、第三引数$with_commentsは他のコメントを含めるかどうかを指定しますが、ここでは標準的な非排他的正規化で、このコメントノード自身の内容のみをファイルに書き出しています。メソッドはファイルに書き込まれたバイト数を整数で返し、処理が失敗した場合はfalseを返します。これにより、コメントの正規化とファイルへの保存が成功したかを確認できます。