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

Copy
1<?php
2
3/**
4 * DOMDocumentFragment の C14NFile メソッドの使用例を示します。
5 * このメソッドは、XMLフラグメントを正規化（Canonical XML）し、その結果を指定されたファイルに書き出します。
6 * 正規化XMLは、異なるXML表現でも内容が同じであることを保証する標準化された形式です。
7 */
8function demonstrateDomDocumentFragmentC14NFile(): void
9{
10    // 1. DOMDocument インスタンスを作成
11    // XMLドキュメント全体の管理や、DOMDocumentFragment の作成に使われます。
12    $dom = new DOMDocument('1.0', 'UTF-8');
13    $dom->formatOutput = true; // 出力を整形する設定（C14Nの結果には直接影響しませんが、デバッグに便利です）
14
15    // 2. DOMDocumentFragment インスタンスを作成
16    // これは、XMLノードのリストを一時的に保持するための軽量なコンテナです。
17    // 親ノードに直接アタッチせずに、XMLコンテンツを構築するのに役立ちます。
18    $fragment = $dom->createDocumentFragment();
19
20    // 3. フラグメントにXMLコンテンツを追加
21    // このXMLが正規化の対象となります。
22    // コメントや属性、異なる要素などが含まれていることを確認できます。
23    $xmlContent = <<<XML
24<root attribute="value">
25    <childElement>Hello, C14N!</childElement>
26    <!-- これは正規化時に含めることができるコメントです -->
27    <anotherChild xmlns:my="http://example.com/ns">
28        <my:data>Namespace Example</my:data>
29    </anotherChild>
30</root>
31XML;
32    $fragment->appendXML($xmlContent);
33
34    // 4. C14NFile メソッドを使用して、フラグメントを正規化しファイルに書き出す
35    $outputFileName = 'canonical_output.xml'; // 正規化されたXMLを保存するファイル名
36
37    // C14NFile(string $uri, bool $exclusive = false, bool $withComments = false, ...)
38    // - $uri: 出力ファイルのパス
39    // - $exclusive: trueの場合、排他的C14Nを使用（デフォルトはfalse）
40    // - $withComments: trueの場合、XMLコメントを正規化された出力に含める（デフォルトはfalse）
41    $bytesWritten = $fragment->C14NFile(
42        $outputFileName,
43        false, // 排他的C14Nは使用しない
44        true   // コメントを含める
45    );
46
47    // 5. 結果の確認
48    if ($bytesWritten === false) {
49        echo "エラー: C14NFile の実行に失敗しました。\n";
50        echo "ファイル '{$outputFileName}' が作成されなかったか、書き込みエラーが発生しました。\n";
51    } else {
52        echo "成功: C14N がファイル '{$outputFileName}' に書き込まれました。\n";
53        echo "書き込まれたバイト数: {$bytesWritten}\n";
54
55        // 生成されたファイルの内容を表示して確認
56        echo "\n--- '{$outputFileName}' の内容 ---\n";
57        echo file_get_contents($outputFileName);
58        echo "---------------------------\n";
59
60        // 注: このサンプルでは生成されたファイルを削除しません。
61        // 内容を確認後、手動で削除するか、必要に応じて unlink($outputFileName); を追加してください。
62    }
63}
64
65// 関数を実行し、デモンストレーションを開始
66demonstrateDomDocumentFragmentC14NFile();
67
68?>

PHPのDOMDocumentFragment::C14NFileメソッドは、XMLの断片（フラグメント）を正規化（Canonical XML）し、その結果を指定されたファイルに保存する機能を提供します。正規化XMLとは、XMLの異なる表記方法を統一し、内容が同一であることを保証するための標準化された形式です。DOMDocumentFragmentは、親ドキュメントに直接追加せずにXMLノードの集合を一時的に保持するコンテナとして機能します。

このメソッドは、第一引数$uriで正規化されたXMLの出力先ファイルパスを受け取ります。第二引数$exclusiveをtrueにすると排他的C14N（Canonical XML 1.0の一部）を適用でき、第三引数$withCommentsをtrueにするとXMLコメントも出力に含めることができます。成功するとファイルに書き込まれたバイト数が整数値で返され、処理が失敗した場合はfalseが返されます。

サンプルコードでは、まずDOMDocumentFragmentにXMLコンテンツを追加し、そのフラグメントに対してC14NFileメソッドを呼び出して、コメントを含めた正規化XMLをcanonical_output.xmlというファイルに書き出しています。これにより、XMLの表現が標準化された形でファイルに保存されることを確認できます。

Copy
1<?php
2
3/**
4 * DOMDocumentFragment::C14NFile の使用例
5 *
6 * この関数は、XMLドキュメントの一部（DOMDocumentFragment）を
7 * 標準的なXML形式（正規化：Canonicalization）に変換し、
8 * その結果を新しいファイルとして保存する方法を示します。
9 * 「cp」というキーワードは「copy」（コピー）を意味することが多いですが、
10 * ここでは単なるファイルのコピーではなく、XMLを特定のルールで整形して
11 * ファイルに書き出す操作として理解してください。
12 *
13 * @return void
14 */
15function demonstrateC14NFile(): void
16{
17    // 1. サンプルXMLデータの準備
18    $xmlString = <<<XML
19<?xml version="1.0" encoding="UTF-8"?>
20<root xmlns:pre="http://example.com/prefix">
21    <item id="1">
22        <name>Product A</name>
23        <description>This is product A.</description>
24    </item>
25    <item id="2">
26        <pre:name>Product B</pre:name>
27        <description>This is product B.</description>
28    </item>
29</root>
30XML;
31
32    // 2. DOMDocumentオブジェクトを作成し、XMLをロード
33    // 第2引数はUTF-8エンコーディングを指定
34    $dom = new DOMDocument('1.0', 'UTF-8');
35    $dom->loadXML($xmlString);
36
37    // 3. DOMDocumentFragmentを作成
38    // このフラグメントに、正規化したいXMLの一部を追加します。
39    $fragment = new DOMDocumentFragment();
40
41    // 例として、XML内の最初の <item> 要素をフラグメントに追加します。
42    // getElementsByTagName('item') で全ての <item> 要素を取得し、item(0) で最初の一つを選択。
43    // cloneNode(true) で子ノードも含めて完全にコピーし、元のDOMツリーに影響を与えません。
44    $targetItemNode = $dom->getElementsByTagName('item')->item(0);
45    if ($targetItemNode) {
46        $fragment->appendChild($targetItemNode->cloneNode(true));
47    } else {
48        echo "エラー: 対象となるXMLの<item>要素が見つかりませんでした。\n";
49        return;
50    }
51
52    // 4. 正規化されたXMLを保存する一時ファイルのパスを準備
53    // sys_get_temp_dir() でシステムの一時ディレクトリを取得し、tempnam() でユニークな一時ファイル名を生成
54    $tempFile = tempnam(sys_get_temp_dir(), 'c14n_');
55    if ($tempFile === false) {
56        echo "エラー: 一時ファイルを作成できませんでした。\n";
57        return;
58    }
59
60    echo "正規化されたXMLフラグメントを以下のファイルに書き出します: " . $tempFile . "\n";
61
62    // 5. C14NFileメソッドを呼び出し、フラグメントを正規化してファイルに書き出す
63    // 第1引数: 保存先のファイルパス (URI)
64    // 第2引数: exclusive C14N (排他的正規化) を使用するか。通常はfalseで標準的な正規化。
65    // 第3引数: コメントを正規化された出力に含めるか。通常はfalseで含めない。
66    // 戻り値: 書き込まれたバイト数 (int) または失敗時は false
67    $bytesWritten = $fragment->C14NFile($tempFile, false, false);
68
69    if ($bytesWritten === false) {
70        echo "エラー: フラグメントの正規化とファイルへの書き出しに失敗しました。\n";
71    } else {
72        echo $bytesWritten . "バイトのXMLがファイルに正常に書き出されました。\n";
73        echo "--- 正規化されたファイルの内容 ---\n";
74        // file_get_contents() でファイルの内容を読み込み、表示
75        echo file_get_contents($tempFile);
76        echo "---------------------------------\n";
77    }
78
79    // 6. 後処理: 作成した一時ファイルを削除
80    if (file_exists($tempFile)) {
81        unlink($tempFile);
82        echo "一時ファイル " . $tempFile . " を削除しました。\n";
83    }
84}
85
86// 関数を実行
87demonstrateC14NFile();

DOMDocumentFragment::C14NFileメソッドは、XMLドキュメントの一部（フラグメント）を、標準的なXML形式である「正規化（Canonicalization）」された形式に変換し、その結果を指定したファイルに保存する機能を提供します。この「正規化」とは、XMLの記述方法の差異（空白や属性の順序など）を吸収し、常に同じ一貫した形式に変換する処理を指します。システムエンジニアを目指す初心者の方には、「cp」（コピー）というキーワードから単純なファイルコピーを連想しがちですが、本メソッドはXMLを特定のルールで整形してからファイルに書き出す点が異なります。

サンプルコードでは、まずXMLデータを読み込み、その一部である最初の <item> 要素を DOMDocumentFragment オブジェクトに設定しています。その後、このフラグメントに対して C14NFile メソッドを呼び出します。第一引数 $uri には、正規化されたXMLを保存するファイルパスを指定します。第二引数 $exclusive は排他的正規化を行うか、第三引数 $withComments はコメントを正規化された出力に含めるかを示し、通常はデフォルト値で問題ありません。メソッドはファイルに書き込んだバイト数を整数で返しますが、処理に失敗した場合は false を返します。このようにして、XMLの一部を決められた形式でファイルに出力し、その内容を確認することができます。この機能は、XMLのデジタル署名やXML同士の厳密な比較が必要な場面で役立ちます。