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

Copy
1<?php
2
3// PHP 8 の Dom 拡張を使用して、XML ドキュメントを正規化 (Canonicalization) し、ファイルに保存するサンプルです。
4// リファレンス情報では Dom\CDATASection::C14NFile とありましたが、
5// 実際には Dom\Document::canonicalizeToFile メソッドがこの機能を提供します。
6
7/**
8 * XMLドキュメントを正規化（Canonicalization）してファイルに保存します。
9 *
10 * @param string $xmlString 正規化したいXML文字列。
11 * @param string $outputUri 正規化されたXMLを保存するファイルパス。
12 * @param bool $exclusive 排他的C14Nを使用するかどうか (デフォルト: false)。
13 * @param bool $withComments コメントを含めるかどうか (デフォルト: false)。
14 * @param ?array $xpath 正規化するノードを特定するためのXPathクエリの配列 (オプション)。
15 * @param ?array $nsPrefixes 正規化する名前空間プレフィックスの配列 (オプション)。
16 * @return int|false 書き込まれたバイト数、または失敗した場合は false。
17 */
18function saveCanonicalizedXmlToFile(
19    string $xmlString,
20    string $outputUri,
21    bool $exclusive = false,
22    bool $withComments = false,
23    ?array $xpath = null,
24    ?array $nsPrefixes = null
25): int|false {
26    // Dom\Document の新しいインスタンスを作成
27    $document = new Dom\Document();
28
29    // 提供されたXML文字列をDOMドキュメントにロード
30    if (!$document->loadXML($xmlString)) {
31        echo "エラー: XML文字列のロードに失敗しました。\n";
32        return false;
33    }
34
35    // ドキュメントを正規化して指定されたファイルに保存
36    // Dom\Document::canonicalizeToFile メソッドは、リファレンス情報にある C14NFile の引数と互換性があります。
37    $bytesWritten = $document->canonicalizeToFile(
38        $outputUri,
39        $exclusive,
40        $withComments,
41        $xpath,
42        $nsPrefixes
43    );
44
45    if ($bytesWritten === false) {
46        echo "エラー: XMLの正規化とファイルへの保存に失敗しました ('{$outputUri}')。\n";
47    } else {
48        echo "XMLを'{$outputUri}'に正常に正規化し、{$bytesWritten}バイト書き込みました。\n";
49    }
50
51    return $bytesWritten;
52}
53
54// --- 使用例 ---
55// サンプルとなるXMLデータ
56$sampleXml = <<<'XML'
57<?xml version="1.0" encoding="UTF-8"?>
58<root xmlns:ex="http://example.com/ns">
59    <!-- これはコメントです -->
60    <ex:element attribute="value">
61        Hello
62        <![CDATA[ <tag>CDATAコンテンツ</tag> ]]>
63        World!
64    </ex:element>
65</root>
66XML;
67
68// 正規化されたXMLを保存するファイルパス
69$outputFilePath = 'canonical_output.xml';
70
71// 最も基本的な形でXMLを正規化し、ファイルに保存します。
72// （デフォルト引数: コメントなし、排他的C14Nなし、XPath/名前空間なし）
73$result = saveCanonicalizedXmlToFile($sampleXml, $outputFilePath);
74
75if ($result !== false) {
76    echo "ファイル '{$outputFilePath}' を確認して、正規化されたXML内容を見てください。\n";
77}
78
79// このサンプルを実行するたびにファイルが生成されます。
80// テスト後に生成されたファイルを削除するには、以下の行のコメントを解除してください。
81// if (file_exists($outputFilePath)) {
82//     unlink($outputFilePath);
83// }

このPHPのサンプルコードは、XMLドキュメントを「正規化（Canonicalization）」し、その結果をファイルに保存する方法を初心者向けに説明しています。正規化とは、XMLの表記の揺れをなくし、内容の一貫性を保証する重要な処理です。

提供されたリファレンス情報ではDom\CDATASection::C14NFileが示されていましたが、実際の機能はDom\Document::canonicalizeToFileメソッドによって提供されます。このメソッドは、Dom\DocumentインスタンスにロードされたXMLをC14Nアルゴリズムに基づいて変換し、指定されたファイルパス（$uri）に出力します。

引数$exclusiveをtrueに設定すると排他的正規化が適用され、$with_commentsをtrueにするとコメントが正規化後の出力に含まれます。$xpathや$ns_prefixes引数を使用することで、正規化するXMLノードや名前空間プレフィックスを細かく指定することも可能です。

メソッドは、処理が成功した場合には書き込まれたバイト数を整数（int）で返し、ファイルへの書き込みやXMLの解析に失敗した場合にはfalseを返します。この機能は、XMLベースの署名やセキュリティ関連の処理、あるいは異なるシステム間でのXMLデータの比較において、その信頼性を高めるために利用されます。

Copy
1<?php
2
3/**
4 * Dom\CDATASection::C14NFile メソッドの使用例。
5 *
6 * このメソッドは、指定された DOM ノード（この場合は CDATA セクション）をXML正規化（C14N）し、
7 * その結果を指定されたファイルに書き込みます。
8 * キーワード「php cp」はファイル操作を連想させますが、このメソッドはファイルを「コピー」するのではなく、
9 * 「正規化されたXMLをファイルに書き出す」という点で関連付けられます。
10 *
11 * システムエンジニアを目指す初心者向けに、DOM要素の作成からファイルへの書き出し、
12 * そしてクリーンアップまでの一連の流れを簡潔に示します。
13 */
14function createCDataNormalizedFile(): void
15{
16    // 出力ファイルの名前を定義します。
17    $outputFileName = 'cdata_normalized_output.xml';
18
19    // 1. XML ドキュメントオブジェクトを作成します。
20    $dom = new DOMDocument('1.0', 'UTF-8');
21    // 出力XMLを見やすくするためにフォーマットを有効にします。
22    $dom->formatOutput = true;
23
24    // 2. ルート要素を作成し、ドキュメントに追加します。
25    $rootElement = $dom->createElement('dataContainer');
26    $dom->appendChild($rootElement);
27
28    // 3. CDATA セクションの内容を定義します。
29    // XMLパーサに内容を文字データとして扱うように指示します。
30    $cdataContent = 'This is some <raw data> with special characters like & and < and >.';
31    
32    // 4. CDATA セクションノードを作成します。
33    $cdataSection = $dom->createCDATASection($cdataContent);
34
35    // 5. CDATA セクションをルート要素に追加します。
36    // これにより、CDATA セクションが DOM ツリーの一部になります。
37    $rootElement->appendChild($cdataSection);
38
39    echo "--- Dom\CDATASection::C14NFile の実行 ---\n";
40    echo "出力ファイル: {$outputFileName}\n";
41    echo "CDATAセクションの内容:\n";
42    echo $cdataContent . "\n\n";
43
44    // 6. CDATA セクションノードを正規化し、ファイルに書き込みます。
45    // C14NFile は Dom\Node クラスのメソッドであり、Dom\CDATASection は Dom\Node を継承しています。
46    // この場合、CDATAセクション自体が持つ正規化された内容がファイルに書き込まれます。
47    // 引数: $uri (ファイルパス), $exclusive (排他的正規化), $with_comments (コメントを含めるか)
48    $bytesWritten = $cdataSection->C14NFile($outputFileName, false, false);
49
50    if ($bytesWritten !== false) {
51        echo "ファイル '{$outputFileName}' に {$bytesWritten} バイトが正常に書き込まれました。\n";
52        echo "書き込まれたファイルの内容:\n";
53        // ファイルの内容を読み込んで表示します。
54        echo file_get_contents($outputFileName) . "\n\n";
55    } else {
56        echo "エラー: ファイル '{$outputFileName}' への書き込みに失敗しました。\n\n";
57    }
58
59    // 7. クリーンアップ: 作成された一時ファイルを削除します。
60    if (file_exists($outputFileName)) {
61        unlink($outputFileName);
62        echo "一時ファイル '{$outputFileName}' を削除しました。\n";
63    }
64    echo "--- 処理終了 ---\n";
65}
66
67// 関数を実行します。
68createCDataNormalizedFile();

Dom\CDATASection::C14NFileメソッドは、PHPでXMLドキュメント内の特定のCDATAセクションの内容をXML正規化（C14N）し、その結果を指定されたファイルに書き出す際に使用します。XML正規化とは、XMLデータの内容は変えずに、その表現を標準的な形式に整える処理のことです。これにより、異なるシステム間でXMLデータを確実に比較したり、デジタル署名などに利用したりできます。

このメソッドは、第一引数$uriで指定されたファイルパスに正規化されたXMLデータを書き込みます。引数$exclusiveは排他的正規化（XML名前空間宣言の扱い）を行うかを、$with_commentsはXMLコメントを含めるかをブール値で指定します。戻り値としては、ファイルに書き込まれたバイト数が整数値で返され、書き込みに失敗した場合はfalseが返されます。

サンプルコードでは、特殊文字を含むテキストをCDATAセクションとして作成し、それをXMLドキュメントに追加しています。その後、このCDATAセクションに対してC14NFileメソッドを呼び出し、正規化された内容を新しいXMLファイルとして保存しています。キーワード「php cp」からファイルコピーを連想するかもしれませんが、このメソッドはファイルをそのままコピーするのではなく、XMLデータを加工・整形して出力する点で異なります。この機能は、安全なXMLデータのやり取りや、データの整合性検証に役立ちます。