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

Copy
1<?php
2
3/**
4 * DOMText::C14NFile メソッドの使用例
5 * XMLドキュメント内の特定のテキストノードを正規化し、ファイルに保存します。
6 */
7function demonstrateDomTextC14NFile(): void
8{
9    // 正規化されたテキストを保存するファイル名
10    $outputFile = 'canonicalized_text.xml';
11
12    // DOMDocumentインスタンスを作成し、XML構造を構築
13    $dom = new DOMDocument('1.0', 'UTF-8');
14    $dom->formatOutput = true; // 出力を読みやすくするため
15
16    $root = $dom->createElement('root');
17    $dom->appendChild($root);
18
19    $element = $dom->createElement('data');
20    $root->appendChild($element);
21
22    // DOMTextノードを作成し、要素に追加
23    $textNodeContent = 'Hello, XML Canonicalization!';
24    $textNode = $dom->createTextNode($textNodeContent);
25    $element->appendChild($textNode);
26
27    echo "元のXML構造:\n";
28    echo $dom->saveXML() . "\n";
29
30    // DOMTextノードに対してC14NFileメソッドを呼び出す
31    // このメソッドは、対象のノード（ここではテキストノード）の内容のみを正規化し、指定されたファイルに書き込みます。
32    $bytesWritten = $textNode->C14NFile($outputFile);
33
34    if ($bytesWritten !== false) {
35        echo "DOMTextノードの正規化に成功しました。\n";
36        echo "内容が '{$outputFile}' に {$bytesWritten} バイトで書き込まれました。\n";
37        echo "--- ファイル内容 ---\n";
38        echo file_get_contents($outputFile) . "\n";
39        echo "--------------------\n";
40    } else {
41        echo "DOMTextノードの正規化に失敗しました。\n";
42    }
43
44    // クリーンアップ: 作成されたファイルを削除
45    if (file_exists($outputFile)) {
46        unlink($outputFile);
47        echo "一時ファイル '{$outputFile}' を削除しました。\n";
48    }
49}
50
51// 関数を実行
52demonstrateDomTextC14NFile();
53
54?>

DOMText::C14NFileメソッドは、PHPのDOM拡張機能に属し、XMLドキュメント内の特定のテキストノードの内容をXML正規化アルゴリズムに従って処理し、その結果を指定されたファイルに書き出すために使用されます。正規化とは、XMLの表現方法を統一することで、内容が同じであれば常に同じ表現になるようにすることです。

このメソッドはDOMTextオブジェクト、つまりXMLドキュメント内のテキスト部分に適用されます。主な引数として、正規化された内容を保存するファイルのパスを文字列（$uri）で指定します。その他にも、排他的な正規化（$exclusive）やコメントの出力（$withComments）、正規化の対象をXPath式で限定する（$xpath）などのオプションがありますが、これらは必要に応じて設定します。

戻り値は、ファイルに実際に書き込まれたバイト数を示す整数（int）です。もしファイルへの書き込みや正規化処理が失敗した場合は、falseが返されます。

サンプルコードでは、まずDOMDocumentとDOMTextを使用して「Hello, XML Canonicalization!」というテキストを含むXML構造を作成しています。その後、このDOMTextノードに対してC14NFileメソッドを呼び出し、テキストの内容を正規化してcanonicalized_text.xmlというファイルに保存しています。処理が成功すれば書き込まれたバイト数が表示され、ファイル内容を確認できます。これにより、特定のテキストノードの情報を厳密に比較・検証したい場合に、このメソッドが役立つことを示しています。

Copy
1<?php
2
3/**
4 * 指定されたXML文字列からDOMTextノードを抽出し、その内容をC14N形式でファイルに書き出します。
5 *
6 * DOMText::C14NFile() メソッドは、指定されたDOMTextノードのサブツリーを
7 * XML正規化 (Canonical XML) 形式でファイルに書き出します。
8 * この例ではDOMTextノードに対して呼び出すため、ノードのテキストデータそのものが正規化された形式として書き出されます。
9 * キーワード 'cp' (コピー) に関連付けて、XMLのテキストコンテンツを正規化して別のファイルに出力する操作を示します。
10 *
11 * @param string $xmlContent XML文字列。
12 * @param string $outputFilePath 正規化されたコンテンツを書き出すファイルのパス。
13 * @return int|false 成功した場合は書き込まれたバイト数、失敗した場合は false。
14 */
15function exportXmlTextNodeAsC14NFile(string $xmlContent, string $outputFilePath): int|false
16{
17    // DOMDocumentを初期化し、XML文字列を読み込む
18    $dom = new DOMDocument('1.0', 'UTF-8');
19    // XMLエラーを抑制し、代わりにloadXMLの戻り値で処理する
20    libxml_use_internal_errors(true);
21    $loaded = $dom->loadXML($xmlContent);
22    libxml_clear_errors(); // エラー情報をクリア
23
24    if (!$loaded) {
25        // XMLの読み込みに失敗した場合
26        error_log("Failed to load XML content.");
27        return false;
28    }
29
30    // 例として、XML内の最初の<item>要素に直接含まれるテキストノードを取得します。
31    // 実際のアプリケーションでは、DOMXPathなどを使用して特定のテキストノードを
32    // より正確に選択することが一般的です。
33    $itemElements = $dom->getElementsByTagName('item');
34    if ($itemElements->length === 0) {
35        error_log("No <item> elements found in XML. Cannot find a text node.");
36        return false;
37    }
38
39    $firstItem = $itemElements->item(0); // 最初の<item>要素を取得
40    $textNode = null;
41
42    // 最初の<item>要素の直接の子ノードを走査し、DOMTextノードを探す
43    foreach ($firstItem->childNodes as $childNode) {
44        if ($childNode instanceof DOMText) {
45            // 最初に見つかったDOMTextノードを使用
46            $textNode = $childNode;
47            break;
48        }
49    }
50
51    if ($textNode === null) {
52        error_log("No direct text node found within the first <item> element. Ensure XML structure has direct text content.");
53        return false;
54    }
55
56    // DOMText::C14NFile() メソッドを呼び出し、正規化された内容をファイルに書き出す
57    // 第1引数: 出力ファイルパス ($uri)
58    // 第2引数: exclusive (排他的正規化) - false を指定すると通常正規化
59    // 第3引数: withComments (コメントを含めるか) - false を指定するとコメントは含めない
60    // DOMTextノードのサブツリーは、そのテキストノード自身となるため、
61    // ここではテキストノードのデータがそのままファイルに書き込まれます。
62    $bytesWritten = $textNode->C14NFile($outputFilePath, false, false);
63
64    return $bytesWritten;
65}
66
67// --- 使用例 ---
68
69// サンプルXMLデータ
70$sampleXml = <<<XML
71<?xml version="1.0" encoding="UTF-8"?>
72<root>
73    <item id="1">This is a sample text node content.</item>
74    <item id="2">Another item with different text.</item>
75    <item id="3"> Mixed <b>content</b> here. </item>
76</root>
77XML;
78
79// 出力ファイルのパスを指定
80$outputFile = __DIR__ . '/canonicalized_text.txt';
81
82// 関数を実行し、結果を出力
83$result = exportXmlTextNodeAsC14NFile($sampleXml, $outputFile);
84
85if ($result !== false) {
86    echo "C14N形式で " . $result . " バイトを '" . realpath($outputFile) . "' に書き込みました。\n";
87    echo "\n--- 書き出されたファイルの内容 ---\n";
88    // 書き出されたファイルの内容を確認のため表示
89    echo file_get_contents($outputFile);
90    echo "\n----------------------------------\n";
91} else {
92    echo "C14N形式でのファイル書き出しに失敗しました。\n";
93}
94
95// 注意: このサンプルコードでは、最初の<item>要素の直接のテキストコンテンツ
96// "This is a sample text node content." がファイルに書き込まれます。
97// XML正規化は通常、要素やドキュメント全体に対して行われることが多いですが、
98// 指定されたDOMTextクラスのメソッドに従って動作しています。
99
100// テスト後のクリーンアップ（必要に応じてコメント解除）
101// if (file_exists($outputFile)) {
102//     unlink($outputFile);
103//     echo "一時ファイル '" . $outputFile . "' を削除しました。\n";
104// }
105
106?>

DOMText::C14NFileメソッドは、PHPのDOM拡張機能の一つで、XMLドキュメント内の特定のテキストノードの内容をXML正規化（Canonical XML）形式でファイルに書き出す際に使用します。

このメソッドは、呼び出されたDOMTextオブジェクト（テキストノード）が保持するテキストデータそのものをXML正規化の対象とします。正規化されたテキストは、指定されたファイルパスへ「コピー」するように出力され、XMLのテキストコンテンツを厳密で一貫性のある標準形式で保存できます。

引数のうち、string $uriには正規化されたコンテンツを書き出すファイルのパスを指定します。bool $exclusiveは排他的正規化を行うかどうかを、bool $withCommentsはXMLコメントを含めるかどうかを真偽値で指定し、通常はfalseを選択します。?array $xpathと?array $nsPrefixesは、本来サブツリー全体を正規化する際に特定の要素や名前空間を制御するためのものですが、DOMTextノードに対するこのメソッドではテキストデータそのものが対象となるため、通常は使用しません。

メソッドの戻り値は、処理が成功した場合はファイルに書き込まれたバイト数を整数で返し、失敗した場合はfalseを返します。

サンプルコードでは、与えられたXML文字列から特定のテキストノードを抽出し、その内容をこのC14NFileメソッドを使って正規化された形式でファイルに保存する具体的な手順を示しています。これは、XMLドキュメントから特定のテキスト情報を安全かつ標準的な方法で別ファイルに抽出したい場合に役立ちます。