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

Copy
1<?php
2
3// このサンプルコードは、DOMDocumentを使用してXMLを読み込み、
4// その内容をCanonical XML (C14N) 形式でファイルに保存する方法を示します。
5// C14Nは、XMLドキュメントの正規表現を生成するために使用され、
6// ドキュメント間の比較やデジタル署名の生成に役立ちます。
7
8// サンプルXMLドキュメントを作成
9$xmlString = <<<XML
10<root xmlns:my="http://example.com/ns">
11    <!-- これは重要なコメントです -->
12    <my:element id="1">
13        Hello &amp; World!
14    </my:element>
15    <element2 attribute="value"/>
16</root>
17XML;
18
19// 新しいDOMDocumentオブジェクトを作成
20$dom = new DOMDocument('1.0', 'UTF-8');
21
22// ホワイトスペースを保持しない設定は、C14Nの結果の一貫性を保つために重要です。
23// 特に、要素間の改行などがC14Nの出力に影響を与えるのを防ぎます。
24$dom->preserveWhiteSpace = false;
25// フォーマット出力はデバッグ目的には便利ですが、C14Nの出力自体には影響しません。
26$dom->formatOutput = true;
27
28// XML文字列をDOMDocumentにロード
29$dom->loadXML($xmlString);
30
31// Canonical XMLの出力先ファイルパスを定義します。
32// __DIR__ は現在のスクリプトがあるディレクトリを指します。
33$outputFile = __DIR__ . '/canonicalized_output.xml';
34
35// Dom\Node::C14NFile メソッドを使用して、DOMドキュメント全体をC14N化し、ファイルに保存します。
36// このメソッドは、DOMDocument（Dom\Nodeを継承）のインスタンスで呼び出せます。
37//
38// 引数:
39// 1. $uri (string): C14N化されたXMLを保存するファイルのURIまたはパス。
40// 2. $exclusive (bool, オプション): 排他的C14Nを使用するかどうか。デフォルトは false (非排他的C14N)。
41// 3. $withComments (bool, オプション): コメントを出力に含めるかどうか。デフォルトは false。
42// 4. $xpath (array, オプション): 特定のノードのみをC14N化する場合のXPathクエリの配列。
43// 5. $nsPrefixes (array, オプション): 排他的C14Nで使用する名前空間プレフィックスの配列。
44//
45// 戻り値:
46// ファイルに書き込まれたバイト数 (int) または失敗した場合 (false)。
47
48echo "XMLをC14N形式でファイルに保存を試行中: {$outputFile}\n";
49
50// 今回は、コメントを含めた非排他的C14N出力を生成します。
51// 第2引数は false (非排他的C14N)、第3引数は true (コメントを含める) です。
52$bytesWritten = $dom->C14NFile($outputFile, false, true);
53
54if ($bytesWritten !== false) {
55    echo "C14N化されたXMLが正常に {$outputFile} に書き込まれました。\n";
56    echo "書き込みバイト数: {$bytesWritten}\n";
57    echo "\n--- {$outputFile} の内容 ---\n";
58    // 生成されたファイルの内容を読み込み、表示します。
59    echo file_get_contents($outputFile);
60    echo "--------------------------\n";
61} else {
62    echo "XMLのC14N化に失敗しました。ファイルへの書き込みができませんでした。\n";
63}
64
65// サンプル実行後に作成された一時ファイルをクリーンアップします。
66if (file_exists($outputFile)) {
67    unlink($outputFile);
68    echo "クリーンアップ: {$outputFile} を削除しました。\n";
69}
70
71?>

このPHPサンプルコードは、DOMDocumentオブジェクトのDom\Node::C14NFileメソッドを使って、XMLドキュメントをCanonical XML（C14N）形式でファイルに保存する方法を示します。C14Nは、XMLの内容を標準形式に正規化し、ドキュメント間の比較やデジタル署名に役立つ技術です。

コードでは、まずXML文字列をDOMDocumentに読み込みます。C14N出力の一貫性を保つため、preserveWhiteSpaceプロパティをfalseに設定しています。

C14NFileメソッドは、保存先ファイルパス（$uri）、排他的C14Nの有無（$exclusive）、コメントの含否（$withComments）を引数で指定します。このサンプルでは、非排他的C14Nでコメントを含める設定です。特定のノードを対象とする$xpathや名前空間プレフィックスの$nsPrefixesなどのオプション引数も利用可能です。

メソッドは、ファイルに書き込まれたバイト数を整数で返すか、処理が失敗した場合にはブール値falseを返します。処理が成功すると、C14N形式のXMLが指定ファイルに保存され、その内容が確認できます。

Copy
1<?php
2
3/**
4 * Dom\Node::C14NFile メソッドを使用して、XML ドキュメントを正規化しファイルに保存します。
5 *
6 * この関数は、指定されたXML文字列をDOMDocumentにロードし、その内容を正規化（Canonicalization）して
7 * 新しいファイルに書き出します。「php cp」というキーワードに対し、
8 * XMLの構造を保ちつつ、標準的な形式で別のファイルに出力する（コピーする）という文脈で関連付けられます。
9 */
10function canonicalizeXmlToFile(): void
11{
12    // 1. サンプルXMLコンテンツを定義
13    // このXMLは、正規化の動作を示すために、コメントと名前空間を含んでいます。
14    $xmlContent = <<<XML
15<?xml version="1.0" encoding="UTF-8"?>
16<root xmlns:ns="http://example.com/ns">
17    <!-- このコメントは withComments = true の場合にのみ出力に含まれます -->
18    <element id="1">
19        <ns:child attribute="value">テキスト内容</ns:child>
20    </element>
21</root>
22XML;
23
24    // 2. DOMDocument オブジェクトを初期化し、XMLをロード
25    $dom = new DOMDocument();
26    $dom->loadXML($xmlContent);
27
28    // 3. 正規化されたXMLを保存する出力ファイルパスを定義
29    // このファイルはスクリプト実行ディレクトリに作成されます。
30    $outputFilePath = __DIR__ . '/canonicalized_output.xml';
31
32    // 4. Dom\Node::C14NFile メソッドを呼び出してXMLを正規化し、ファイルに保存
33    // 引数:
34    //   $uri (string): 正規化されたXMLを書き込むファイルパス。
35    //   $exclusive (bool): 排他的な正規化（Exclusive XML Canonicalization）を使用するか。ここでは false。
36    //   $withComments (bool): 出力にコメントを含めるか。ここでは true に設定し、コメントが含まれることを示します。
37    $bytesWritten = $dom->C14NFile($outputFilePath, false, true);
38
39    if ($bytesWritten !== false) {
40        echo "XMLが正常に正規化され、ファイルに保存されました。\n";
41        echo "出力ファイル: " . $outputFilePath . "\n";
42        echo "書き込まれたバイト数: " . $bytesWritten . "\n\n";
43
44        // 保存されたファイルの内容を表示して確認
45        echo "--- 正規化されたXMLの内容 ---\n";
46        echo file_get_contents($outputFilePath);
47        echo "\n-----------------------------\n";
48
49        // 後処理: 生成されたファイルを削除
50        if (file_exists($outputFilePath)) {
51            unlink($outputFilePath);
52            echo "\n出力ファイル '" . basename($outputFilePath) . "' は削除されました。\n";
53        }
54    } else {
55        echo "XMLの正規化とファイルへの保存に失敗しました。\n";
56        // エラーの詳細はC14NFileからは直接取得できないため、環境設定やXML内容を確認してください。
57    }
58}
59
60// 関数を実行
61canonicalizeXmlToFile();
62

Dom\Node::C14NFileメソッドは、PHPでXMLドキュメントを「正規化」（Canonicalization）し、その内容をファイルに保存するための機能です。XMLの正規化とは、同じ論理的な情報を持つXMLドキュメントであっても、属性の順序や名前空間の宣言方法といった表現の違いを吸収し、常に一貫した標準的な形式に変換するプロセスを指します。この特性から、「php cp」というキーワードに対し、XMLデータを構造を保ちながら標準的な形式で別のファイルに「コピー」するという文脈で関連付けられます。

サンプルコードでは、まずXML文字列をDOMDocumentオブジェクトに読み込みます。次に、C14NFileメソッドを呼び出すことで、このXMLドキュメントが正規化され、指定されたファイルパス（$uri引数）に保存されます。$exclusive引数は排他的正規化を行うかどうかを、$withComments引数はコメントを正規化された出力に含めるかどうかを制御します。このメソッドは、ファイルに書き込まれたバイト数を整数で返し、処理が失敗した場合にはfalseを返します。これにより、XMLの内容を一貫した形式で安全に管理し、異なるシステム間での比較や署名検証に利用できるようになります。