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

C14NFileメソッドの使い方について、初心者にもわかりやすく解説します。

作成日: 2025年09月11日更新日: 2025年11月08日

基本的な使い方

Dom\HTMLDocumentクラスのC14NFileメソッドは、ドキュメントを標準形式（Canonical XML）でファイルに保存するメソッドです。このメソッドを使用すると、HTMLドキュメントを、XML標準のC14N（Canonical XML）形式に変換し、指定されたファイルパスに書き出すことができます。C14N形式は、XMLドキュメントの論理的な内容を保持しつつ、空白や属性の順序など、形式上の差異を正規化することで、一貫した表現を提供します。これにより、異なるシステム間でのドキュメントの比較や検証が容易になります。

C14NFileメソッドは、ファイルパスを引数として受け取ります。オプションで、排他的なC14N形式を使用するかどうか、コメントを含めるかどうか、プレフィックスリストを指定するかどうかなどのパラメータを設定できます。これらのオプションを使用することで、C14N形式の出力を細かく制御できます。

このメソッドは、ドキュメントをファイルに保存する際にエラーが発生した場合（例えば、ファイルパスが無効な場合や、書き込み権限がない場合など）は、falseを返します。成功した場合はtrueを返します。C14NFileメソッドは、XMLドキュメントの正規化された形式をファイルに保存する必要がある場合に非常に有用です。例えば、デジタル署名を作成する前や、ドキュメントの整合性を検証する前などに使用されます。

構文(syntax)


1Dom\HTMLDocument::C14NFile(string $uri, bool $exclusive = false, bool $withComments = false, array $xpath = null, ?string $nsPrefix = null): int|false

引数(parameters)

string $uri, bool $exclusive = false, bool $with_comments = false, ?array $xpath = null, ?array $ns_prefixes = null

string $uri: 正規化するHTMLドキュメントのURIを指定します。
bool $exclusive = false: trueを指定すると、指定されたXPathにマッチする要素のみを正規化します。
bool $with_comments = false: trueを指定すると、コメントノードも正規化の対象に含めます。
?array $xpath = null: $exclusiveがtrueの場合に、正規化対象とする要素を指定するXPathクエリの配列です。
?array $ns_prefixes = null: XPathクエリで使用する名前空間プレフィックスをマッピングする連想配列です。

戻り値(return)

int|false

C14NFileメソッドは、XML/HTML文書を正規化してファイルに保存した結果を整数値、または失敗した場合はfalseで返します。成功した場合は、正規化されたバイト数を示す整数が返されます。

サンプルコード

PHP 8 Dom C14NFile でHTMLを正規化してファイル出力


1<?php
2
3// このスクリプトは、PHP 8 の Dom\HTMLDocument クラスの C14NFile メソッドの使用例を示します。
4// C14NFile は、HTMLドキュメントを正規化されたXML（Canonical XML）として指定されたファイルに書き出します。
5// Canonical XML (C14N) は、XML文書の異なる表現が意味的に同一であるかを判断するための標準的な形式です。
6
7// 1. 正規化したいHTMLコンテンツを文字列として定義します。
8$htmlContent = <<<HTML
9<!DOCTYPE html>
10<html>
11<head>
12    <meta charset="utf-8">
13    <title>C14NFile サンプル</title>
14</head>
15<body>
16    <!-- これはHTMLコメントです。C14NFileのwith_commentsオプションがtrueの場合に出力されます。 -->
17    <p class="greeting">こんにちは、<span>世界</span>！</p>
18    <p>PHP 8 Dom\\HTMLDocument::C14NFile メソッドのテストです。</p>
19</body>
20</html>
21HTML;
22
23// 2. 正規化されたXMLを保存するファイルパスを指定します。
24// このスクリプトが実行されるディレクトリに 'canonical_output.xml' が作成されます。
25$outputFilePath = __DIR__ . '/canonical_output.xml';
26
27try {
28    // 3. Dom\HTMLDocument の新しいインスタンスを作成します。
29    // これは PHP 8 以降で導入された新しい DOM 拡張の一部です。
30    $document = new Dom\HTMLDocument();
31
32    // 4. 定義したHTMLコンテンツをドキュメントにロードします。
33    // loadHTML メソッドはHTML文字列をパースし、DOMツリーを構築します。
34    $document->loadHTML($htmlContent);
35
36    // 5. C14NFile メソッドを呼び出し、正規化されたXMLをファイルに書き出します。
37    // 引数:
38    //   $uri: 出力先のファイルパス（必須）。
39    //   $exclusive: 排他的正規化を行うか (bool, デフォルトは false)。
40    //   $with_comments: コメントを含めるか (bool, デフォルトは false)。今回は true に設定し、コメントも出力されるようにします。
41    //   $xpath: (オプション) 特定のノードのみを対象とするXPath式。
42    //   $ns_prefixes: (オプション) 名前空間プレフィックスの配列。
43    // 戻り値: 書き出されたバイト数、または失敗した場合は false。
44    $bytesWritten = $document->C14NFile($outputFilePath, false, true);
45
46    // 6. メソッドの実行結果を確認し、メッセージを表示します。
47    if ($bytesWritten === false) {
48        echo "エラー: Dom\\HTMLDocument::C14NFile メソッドの実行に失敗しました。\n";
49    } else {
50        echo "成功: Canonical XML が '{$outputFilePath}' に書き出されました。({$bytesWritten}バイト)\n\n";
51
52        // 書き出されたファイルの内容をコンソールに表示して確認します。
53        echo "--- '{$outputFilePath}' の内容 ---\n";
54        echo file_get_contents($outputFilePath);
55        echo "\n--------------------------------\n";
56    }
57} catch (Throwable $e) {
58    // 処理中に例外が発生した場合のエラーハンドリング
59    echo "処理中にエラーが発生しました: " . $e->getMessage() . "\n";
60}
61
62// 注意: このスクリプトは 'canonical_output.xml' ファイルを生成します。
63// 実行後に不要な場合は、手動で削除してください。

PHP 8におけるDom\HTMLDocument::C14NFileメソッドは、HTMLドキュメントを正規化されたXML（Canonical XML、C14N）の形式で指定のファイルに出力する機能を提供します。C14Nとは、XML文書の異なる書き方を、内容が同じであれば一意の標準形式に変換するための規則で、これにより文書間の厳密な比較などが容易になります。

サンプルコードでは、最初にDom\HTMLDocumentのインスタンスを作成し、HTMLコンテンツをloadHTMLメソッドで読み込みます。その後、C14NFileメソッドを呼び出し、第一引数に出力先のファイルパスを指定します。第二引数は排他的正規化を行うかどうか、第三引数はHTMLコメントを出力に含めるかどうかを設定するもので、サンプルではコメントを含めるようtrueに設定しています。その他、特定の要素のみを対象とするXPathや名前空間プレフィックスも任意で指定できます。このメソッドは、正常にファイルへ書き出されたバイト数を整数で返しますが、処理に失敗した場合はfalseを返しますので、その戻り値で成功・失敗を判断できます。このように、HTMLをXMLとして標準化し、安定した形式で保存したい場合にこのメソッドは役立ちます。

このコードはPHP 8以降で利用可能な新しいDOM拡張であるDom\HTMLDocumentクラスを使っています。C14NFileメソッドは、HTMLコンテンツをXMLの標準化形式（Canonical XML）で指定されたファイルに書き出します。出力先のファイルが既に存在する場合、その内容は上書きされますので、ファイルパスの指定には十分ご注意ください。引数$with_commentsをtrueに設定するとHTMLのコメントも出力に含まれます。メソッドがfalseを返した場合は処理失敗を意味しますので、必ず戻り値を確認し、エラーや例外への適切なハンドリングを行うことが安全な利用のために重要です。

PHP Dom\HTMLDocument C14NFileでHTMLを正規化保存する


1<?php
2
3/**
4 * HTMLドキュメントをCanonical XML (C14N) 形式でファイルに保存するサンプルです。
5 *
6 * システムエンジニアを目指す初心者の方向けに、Dom\HTMLDocument::C14NFile メソッドの
7 * 基本的な使い方を示します。
8 * キーワード「php cp」は、このメソッドがPHPでDOMツリーを処理し、その結果をファイルに
9 * 「コピー」（保存）する機能を持つことに関連しています。
10 *
11 * 注意: Dom\HTMLDocument クラスは PHP 8.2 以降で利用可能です。
12 *
13 * @param string $htmlContent 正規化するHTML文字列。
14 * @param string $outputFilePath 正規化されたHTMLを出力するファイルパス。
15 * @return void
16 */
17function saveCanonicalHtmlToFile(string $htmlContent, string $outputFilePath): void
18{
19    // 新しいDom\HTMLDocumentオブジェクトを作成します。
20    // PHP 8.2以降でこのクラスが利用できます。
21    $document = new Dom\HTMLDocument();
22
23    // 指定されたHTMLコンテンツをドキュメントにロードします。
24    // 無効なHTMLの場合、loadHTMLは警告を生成することがありますが、ここでは抑制します。
25    @$document->loadHTML($htmlContent);
26
27    // Dom\HTMLDocument::C14NFile メソッドを使用して、
28    // ドキュメントの正規化された（Canonical XML）バージョンをファイルに保存します。
29    // C14Nは、XML/HTMLドキュメントの内容をバイトレベルで一意に表現するための標準です。
30    // このメソッドは、ファイルに書き込まれたバイト数を返します。失敗した場合は false です。
31    $bytesWritten = $document->C14NFile($outputFilePath);
32
33    if ($bytesWritten !== false) {
34        echo "成功: 正規化されたHTMLが '{$outputFilePath}' に {$bytesWritten} バイト書き込まれました。\n";
35        echo "生成されたファイルの内容を確認してください。\n";
36    } else {
37        echo "エラー: HTMLコンテンツの正規化およびファイルへの保存に失敗しました。\n";
38    }
39}
40
41// --- サンプル実行 ---
42
43// サンプルとして使用するHTMLコンテンツ
44$sampleHtml = <<<HTML
45<!DOCTYPE html>
46<html>
47<head>
48    <meta charset="utf-8">
49    <title>テストページ</title>
50</head>
51<body>
52    <h1>こんにちは、世界！</h1>
53    <p>これは、<span>テスト</span>の段落です。</p>
54    <!-- これはコメントです -->
55</body>
56</html>
57HTML;
58
59// 正規化されたHTMLを保存するファイルパス
60$outputFile = 'canonical_output.html';
61
62// 関数を呼び出して処理を実行
63saveCanonicalHtmlToFile($sampleHtml, $outputFile);
64
65// 実行後の確認メッセージ
66if (file_exists($outputFile)) {
67    echo "\nファイル '{$outputFile}' が正常に生成されました。\n";
68    echo "ファイルサイズ: " . filesize($outputFile) . " バイト\n";
69    // 必要であれば、生成されたファイルの内容を表示することもできます
70    // echo "--- ファイル内容 ---\n" . file_get_contents($outputFile) . "\n--------------------\n";
71
72    // クリーンアップ: このサンプルコードを再実行する際に古いファイルが残らないようにするため、
73    // またはディスクスペースを節約するために、生成されたファイルを削除する場合があります。
74    // unlink($outputFile);
75    // echo "\nクリーンアップ: 生成されたファイル '{$outputFile}' を削除しました。\n";
76} else {
77    echo "\nエラー: ファイル '{$outputFile}' は生成されませんでした。\n";
78}

このサンプルコードは、PHPのDom\HTMLDocument::C14NFileメソッドを用いて、HTMLドキュメントをCanonical XML（C14N）形式で指定したファイルに保存する方法を、システムエンジニアを目指す初心者の方に分かりやすく解説しています。キーワード「php cp」は、このメソッドがPHPで処理したDOMツリーの内容を、新しいファイルとして「コピー」（保存）する機能を持つことに関連しています。

コードではまず、Dom\HTMLDocumentオブジェクトを生成し、正規化したいHTMLコンテンツを読み込みます。次に、C14NFileメソッドを呼び出し、引数として保存先のファイルパス（$uri）を指定します。このメソッドは、HTMLドキュメントの内容をC14Nという標準形式でファイルに書き込みます。C14N形式は、XMLやHTMLの内容をバイトレベルで一意に表現するための標準であり、ドキュメントの同一性を保証する際に利用されます。メソッドの戻り値は、ファイルに正常に書き込まれたバイト数を整数で返しますが、処理が失敗した場合はfalseを返すため、結果を確認することでエラーハンドリングが可能です。なお、Dom\HTMLDocumentクラスはPHP 8.2以降で利用できます。このサンプルは、HTMLの正規化とファイル出力の基本的な流れを理解するのに役立ちます。

Dom\HTMLDocument::C14NFileメソッドは、HTMLドキュメントをCanonical XML形式でファイルに保存します。このDom\HTMLDocumentクラスはPHP 8.2以降で利用可能ですので、実行環境のPHPバージョンを必ず確認してください。メソッドは、ドキュメントの内容をバイトレベルで一意に表現される形式に正規化し、指定されたファイルパスへ書き込みます。ファイルの書き込みに成功すると書き込まれたバイト数を、失敗するとfalseを返しますので、必ず戻り値をチェックしてエラー処理を行うようにしてください。また、引数で指定するファイルパスには、PHP実行ユーザーが書き込み権限を持つ場所を指定する必要があります。これにより、HTMLの内容を安全かつ確実にファイルへ保存できます。