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

Copy
1<?php
2
3/**
4 * DOMDocumentType::C14NFile メソッドのサンプルコード。
5 *
6 * この関数は、XMLドキュメントからDOCTYPE宣言を取得し、
7 * そのDOCTYPE宣言部分のみをXML正規化 (Canonical XML, C14N) 形式でファイルに保存します。
8 * C14Nは、XMLドキュメントの表記揺れをなくし、一貫した形式に変換するプロセスです。
9 *
10 * @param string $outputFilePath 正規化されたDOCTYPE宣言の出力先ファイルパス。
11 */
12function demonstrateC14NFileForDocumentType(string $outputFilePath): void
13{
14    // C14NFileメソッドを呼び出すためのDOMDocumentTypeオブジェクトを取得するために、
15    // まずはDOCTYPE宣言を含むXMLドキュメントを作成します。
16    // ここでは、シンプルな内部DTDサブセットを持つXMLを使用します。
17    $xmlString = <<<XML
18<!DOCTYPE root [
19  <!ELEMENT root EMPTY>
20]>
21<root/>
22XML;
23
24    // DOMDocumentオブジェクトを初期化し、XML文字列をロードします。
25    $dom = new DOMDocument('1.0', 'UTF-8');
26    // XMLをロードする際にエラーが発生した場合は処理を中断します。
27    if (!$dom->loadXML($xmlString)) {
28        echo "エラー: XML文字列のロードに失敗しました。\n";
29        return;
30    }
31
32    // DOMDocumentTypeオブジェクトは、DOMDocumentの 'doctype' プロパティから取得できます。
33    // このプロパティは、XMLドキュメントのDOCTYPE宣言部を表します。
34    $documentType = $dom->doctype;
35
36    // DOCTYPE宣言がXMLドキュメントに存在するかを確認します。
37    if ($documentType instanceof DOMDocumentType) {
38        echo "DOCTYPEノードを正規化して、ファイルに保存します: {$outputFilePath}\n\n";
39
40        try {
41            // DOMDocumentType::C14NFile メソッドを呼び出します。
42            // これにより、DOCTYPE宣言部分がXML正規化 (C14N) 形式で指定されたファイルに保存されます。
43            //
44            // 引数:
45            // 1. $uri (string): 出力ファイルパス。必須引数です。
46            // 2. $exclusive (bool, 省略可能): 排他的正規化を適用するかどうか (デフォルト: false)。
47            // 3. $withComments (bool, 省略可能): コメントを含めるかどうか (デフォルト: false)。
48            // 4. $xpath (array|null, 省略可能): 正規化するノードをXPathで指定 (デフォルト: null)。
49            // 5. $nsPrefixes (array|null, 省略可能): 名前空間プレフィックスの配列 (デフォルト: null)。
50            //
51            // この例では、最もシンプルな形式で必須引数のみを渡し、
52            // その他の引数はデフォルト値（falseまたはnull）を使用します。
53            $documentType->C14NFile($outputFilePath);
54
55            echo "成功: DOCTYPE宣言の正規化された内容が '{$outputFilePath}' に保存されました。\n";
56
57            // 保存されたファイルの内容を確認のために表示します。
58            if (file_exists($outputFilePath)) {
59                echo "\n--- 保存されたファイル内容 ---\n";
60                echo file_get_contents($outputFilePath);
61                echo "--- ファイル内容ここまで ---\n";
62            }
63        } catch (Throwable $e) {
64            // C14NFileメソッドの実行中にエラーが発生した場合、メッセージを表示します。
65            echo "エラーが発生しました: " . $e->getMessage() . "\n";
66        }
67    } else {
68        echo "エラー: このXMLドキュメントにはDOCTYPE宣言が含まれていません。\n";
69        echo "DOMDocumentType::C14NFile は DOMDocumentType オブジェクトに対して呼び出される必要があります。\n";
70    }
71}
72
73// スクリプトの実行部
74// 正規化されたDOCTYPE宣言を保存するファイルのパスを指定します。
75// このスクリプトと同じディレクトリに 'doctype_c14n_output.xml' が作成されます。
76$outputFile = __DIR__ . '/doctype_c14n_output.xml';
77
78// 以前の実行で作成されたファイルが存在する場合は削除し、クリーンな状態にします。
79if (file_exists($outputFile)) {
80    unlink($outputFile);
81    echo "既存のファイル '{$outputFile}' を削除しました。\n";
82}
83
84// 上記で定義したサンプル関数を実行します。
85demonstrateC14NFileForDocumentType($outputFile);
86
87echo "\nスクリプトの実行が完了しました。\n";
88
89// 必要に応じて、生成されたファイルをスクリプト終了時に自動的に削除する
90// (例: `unlink($outputFile);`) ことができますが、ここでは手動での確認のため残しています。
91
92?>

DOMDocumentType::C14NFileメソッドは、PHPのDOM拡張機能において、XMLドキュメントのDOCTYPE宣言部分をXML正規化（Canonical XML、C14N）形式でファイルに保存するために使用されます。C14Nとは、XMLドキュメントの表記揺れを吸収し、内容を標準的かつ一貫した形式に変換するプロセスで、異なる環境間でのXMLの比較や電子署名などでその重要性が高まります。

このメソッドは、XMLドキュメントのDOCTYPEノードを表すDOMDocumentTypeオブジェクトから呼び出されます。引数として、正規化されたDOCTYPE宣言の内容を書き出すファイルパスを文字列で指定します。これは必須の引数です。その他に、排他的正規化の適用、XMLコメントを含めるかどうか、正規化対象をXPathで指定するなどのオプション引数も提供されていますが、基本的な利用ではファイルパスのみで動作します。メソッドは戻り値を持ちません。処理が成功すれば、指定されたファイルに正規化された内容が書き込まれます。

サンプルコードでは、DOCTYPE宣言を含むXMLを作成し、そこからDOMDocumentTypeオブジェクトを取得しています。そして、取得したオブジェクトに対してC14NFileメソッドを呼び出すことで、DOCTYPE宣言部分のみがC14N形式で指定されたファイルに保存されます。これにより、XMLのDOCTYPE宣言がどのような形式で正規化され、ファイルに書き出されるのかを具体的に確認できる仕組みです。エラー発生時のメッセージ表示も含まれており、初心者がメソッドの挙動を安全に試せるよう配慮されています。

Copy
1<?php
2
3/**
4 * 指定されたXML文字列をC14N (Canonical XML) 形式で正規化し、新しいファイルに保存します。
5 * この関数はDOMDocument::C14NFileメソッドを使用します。
6 *
7 * @param string $xmlContent 正規化するXML文字列。
8 * @param string $outputFilePath 正規化されたXMLを保存するファイルのパス。
9 * @param bool $exclusive 排他的C14Nを使用するかどうか (デフォルト: false)。
10 *                         名前空間の扱いが厳密になり、特定の署名処理などで利用されます。
11 * @param bool $withComments コメントノードを正規化された出力に含めるかどうか (デフォルト: false)。
12 * @return bool 処理が成功した場合はtrue、失敗した場合はfalse。
13 */
14function normalizeXmlToFile(
15    string $xmlContent,
16    string $outputFilePath,
17    bool $exclusive = false,
18    bool $withComments = false
19): bool {
20    // DOMDocumentオブジェクトを作成します。
21    // XMLドキュメント全体の操作に使用します。
22    $dom = new DOMDocument('1.0', 'UTF-8');
23    
24    // XML文字列をDOMDocumentにロードします。
25    // エラーが発生した場合（例: 不正なXML形式）、falseを返します。
26    // @ 演算子は、loadXML()が生成する可能性のある警告を抑制します。
27    if (!@$dom->loadXML($xmlContent)) {
28        echo "エラー: XMLコンテンツのロードに失敗しました。XML形式を確認してください。\n";
29        return false;
30    }
31
32    try {
33        // C14NFileメソッドを呼び出し、XMLを正規化して指定されたファイルに保存します。
34        // このメソッドは戻り値を持ちません。
35        // リファレンス情報ではDOMDocumentTypeに所属とありますが、実際はDOMDocumentのメソッドです。
36        $dom->C14NFile($outputFilePath, $exclusive, $withComments);
37
38        // ファイルが正常に作成され、内容があることを確認します。
39        if (file_exists($outputFilePath) && filesize($outputFilePath) > 0) {
40            return true;
41        } else {
42            echo "エラー: 正規化されたXMLを '" . $outputFilePath . "' に保存できませんでした。ファイルが作成されていないか、空です。\n";
43            return false;
44        }
45    } catch (Throwable $e) {
46        // C14NFile処理中に予期せぬエラーが発生した場合のハンドリング
47        echo "エラー: XMLの正規化中に予期せぬ例外が発生しました: " . $e->getMessage() . "\n";
48        return false;
49    }
50}
51
52// --- サンプルXMLコンテンツの準備 ---
53// テスト用にシンプルなXML構造とコメントを含めます。
54$sampleXml = <<<'XML'
55<?xml version="1.0" encoding="UTF-8"?>
56<bookstore>
57  <book category="cooking">
58    <title lang="en">Everyday Italian</title>
59    <author>Giada De Laurentiis</author>
60    <year>2005</year>
61    <price>30.00</price>
62  </book>
63  <!-- このコメントは、コメントを含む正規化で表示されます -->
64  <book category="children">
65    <title lang="en">Harry Potter</title>
66    <author>J.K. Rowling</author>
67    <year>2005</year>
68    <price>29.99</price>
69  </book>
70</bookstore>
71XML;
72
73// --- 出力ファイルパスの設定 ---
74$outputFileBase = 'canonical_output';
75$outputFileStandard = $outputFileBase . '_standard.xml';
76$outputFileWithComments = $outputFileBase . '_with_comments.xml';
77$outputFileExclusive = $outputFileBase . '_exclusive.xml';
78
79// --- 各種正規化処理の実行と結果の表示 ---
80
81// 1. 標準的な正規化 (コメントなし、排他的C14Nなし)
82echo "--- 1. 標準的なC14N (コメントノードは含まれません) ---\n";
83if (normalizeXmlToFile($sampleXml, $outputFileStandard, false, false)) {
84    echo "正規化されたXMLが '" . $outputFileStandard . "' に保存されました。\n";
85    echo "内容:\n" . file_get_contents($outputFileStandard) . "\n\n";
86} else {
87    echo "標準C14Nの実行に失敗しました。\n\n";
88}
89
90// 2. コメントノードを含む正規化
91echo "--- 2. コメントノードを含むC14N ---\n";
92if (normalizeXmlToFile($sampleXml, $outputFileWithComments, false, true)) {
93    echo "正規化されたXMLが '" . $outputFileWithComments . "' に保存されました。\n";
94    echo "内容:\n" . file_get_contents($outputFileWithComments) . "\n\n";
95} else {
96    echo "コメントノードを含むC14Nの実行に失敗しました。\n\n";
97}
98
99// 3. 排他的C14N (コメントなし)
100// 名前空間を扱うXMLで特に重要ですが、ここでは引数の使い方を示すため利用します。
101// このシンプルなXMLでは、標準C14Nと結果が同じに見える場合があります。
102echo "--- 3. 排他的C14N (コメントノードは含まれません) ---\n";
103if (normalizeXmlToFile($sampleXml, $outputFileExclusive, true, false)) {
104    echo "正規化されたXMLが '" . $outputFileExclusive . "' に保存されました。\n";
105    echo "内容:\n" . file_get_contents($outputFileExclusive) . "\n\n";
106} else {
107    echo "排他的C14Nの実行に失敗しました。\n\n";
108}
109
110
111// --- 生成されたファイルのクリーンアップ ---
112echo "--- 生成されたファイルのクリーンアップ ---\n";
113$filesToClean = [$outputFileStandard, $outputFileWithComments, $outputFileExclusive];
114foreach ($filesToClean as $file) {
115    if (file_exists($file)) {
116        unlink($file); // ファイルを削除します
117        echo "ファイル '" . $file . "' を削除しました。\n";
118    }
119}
120echo "全てのクリーンアップが完了しました。\n";
121
122?>

DOMDocument::C14NFileメソッドは、XMLドキュメントをC14N (Canonical XML) 形式で正規化し、その結果を指定されたファイルに保存する機能を提供します。リファレンス情報ではDOMDocumentTypeに所属とありますが、実際にはDOMDocumentクラスのメソッドとして利用します。

C14Nとは、XMLの表記ゆれ（空白、属性の順序、名前空間宣言など）を統一し、内容が論理的に同じであれば常に同じ形式になるようにする国際標準です。これにより、XMLの比較や電子署名といった、厳密な同一性が求められる場面で役立ちます。

このメソッドには、正規化されたXMLの保存先を示すファイルパスを文字列で指定する$uri引数があります。また、排他的C14Nを適用するかどうかを真偽値で指定する$exclusive引数があり、trueに設定すると名前空間の扱いがより厳密になります。さらに、XML内のコメントノードを正規化後の出力に含めるかを真偽値で指定する$withComments引数も用意されています。これらの引数で正規化の挙動を制御できます。このメソッド自体は戻り値を持ちません。

サンプルコードでは、まずXML文字列をDOMDocumentオブジェクトにロードし、その後C14NFileメソッドを使用して、標準的な正規化、コメントを含む正規化、排他的C14Nの3通りの方法でXMLを正規化し、それぞれ異なるファイルに保存しています。これにより、各引数の違いによる出力の変化を確認できます。処理の最後には、生成されたファイルを削除してクリーンアップを行っています。