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

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

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

基本的な使い方

C14Nメソッドは、ドキュメントを正規化されたXML形式で出力するメソッドです。Dom\HTMLDocumentクラスに属し、HTMLドキュメントをXMLドキュメントとしてC14N（Canonical XML）標準に従ってシリアライズします。C14Nは、XMLドキュメントを比較したり、デジタル署名を作成したりする際に、XMLドキュメントの表現を標準化するために使用されます。

このメソッドは、ドキュメントの構造と内容を標準的な形式に変換し、名前空間の宣言、属性の順序、空白の処理などを一定のルールに従って調整します。これにより、意味的に等価なXMLドキュメントであっても、異なる表現形式を持っている場合に、それらを同一のものとして扱うことができます。

C14Nメソッドは、オプションで排他的C14N（Exclusive XML Canonicalization）を使用できます。排他的C14Nは、指定されたノードセットに影響を与える名前空間宣言のみを保持するため、より厳密な正規化が必要な場合に役立ちます。

このメソッドは、正規化されたXMLドキュメントを文字列として返します。エラーが発生した場合は、falseを返します。システムエンジニアがXMLドキュメントを扱う際、特にセキュリティ関連の処理や異なるシステム間でのデータ交換を行う場合に、C14Nメソッドを利用することで、データの整合性を確保し、潜在的な問題を回避できます。具体的には、電子署名やXMLデータの比較、キャッシュのキー生成などに利用できます。

構文(syntax)


1Dom\HTMLDocument::C14N( ?string $exclusive = null, ?bool $withComments = null, ?array $nodes = null, ?string $namespaceUris = null ) : string|false

引数(parameters)

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

bool $exclusive = false: 特定の要素のみを正規化するかどうかを指定します。trueにすると、指定されたXPathにマッチする要素とその子孫のみが正規化されます。
bool $with_comments = false: コメントノードを正規化に含めるかどうかを指定します。trueにすると、コメントノードも正規化されます。
?array $xpath = null: 正規化の対象を限定するためのXPathクエリの配列を指定します。nullの場合はドキュメント全体が対象となります。
?array $ns_prefixes = null: 名前空間プレフィックスの配列を指定します。正規化時にこれらのプレフィックスのみが考慮されます。

戻り値(return)

string|false

C14Nメソッドは、XML文書を正規化して文字列として返します。正規化に失敗した場合はfalseを返します。

サンプルコード

PHP 8 Dom\HTMLDocument::C14N でXMLを正規化する


1<?php
2
3// システムエンジニアを目指す初心者向けに、XMLの正規化 (Canonical XML, C14N) を行うPHPコードです。
4// C14Nは、XMLドキュメントの内容を一意の形式に変換する標準的な方法であり、
5// 例えば電子署名などでドキュメントの改ざんがないことを検証する際に利用されます。
6// XMLの構造的な等価性をバイト列レベルで確認できるようになります。
7
8// 1. XMLに近いHTMLコンテンツを準備します。
9//    Dom\HTMLDocumentクラスはHTMLを扱いますが、内部的にはXMLと同様のDOMツリーを構築するため、C14Nも適用可能です。
10//    この例では、HTML構造の中にXML要素を埋め込んでいます。
11$xmlishHtml = <<<HTML
12<!DOCTYPE html>
13<html>
14<head>
15    <title>C14N Example</title>
16</head>
17<body>
18    <!-- このコメントはデフォルトのC14N出力には含まれません。 -->
19    <data attribute="value">
20        これは正規化されるテキストです。
21        <child />
22    </data>
23</body>
24</html>
25HTML;
26
27// 2. Dom\HTMLDocument オブジェクトを作成します。
28$dom = new Dom\HTMLDocument();
29
30// 3. HTMLコンテンツをDOMオブジェクトにロードします。
31//    LIBXML_HTML_NOIMPLIED と LIBXML_HTML_NODEFDTD は、
32//    不必要な<html>, <body>タグやDOCTYPE宣言の自動追加を抑制し、元のHTML構造に極力近い形でロードします。
33//    ロードに失敗した場合は false を返すため、エラーハンドリングを行います。
34if (!$dom->loadHTML($xmlishHtml, LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD)) {
35    echo "エラー: HTMLのロードに失敗しました。\n";
36    exit(1);
37}
38
39// 4. Dom\HTMLDocument::C14N メソッドを使ってXMLを正規化します。
40//    引数:
41//      - $exclusive (bool, デフォルト: false): 排他的正規化を行うかどうか。
42//                                                falseの場合、親要素の名前空間宣言も継承されます。
43//                                                trueの場合、自身で必要な名前空間のみ宣言され、よりコンパクトになります。
44//      - $with_comments (bool, デフォルト: false): コメントを正規化された出力に含めるかどうか。
45//      - $xpath (array|null, デフォルト: null): 特定の要素のみを正規化する場合にXPath式を指定します。
46//      - $ns_prefixes (array|null, デフォルト: null): 名前空間プレフィックスのリストを指定します。
47//
48//    この例では引数を指定せず、デフォルト設定 (排他的正規化なし、コメントなし) で実行します。
49$c14nOutput = $dom->C14N();
50
51// 5. 結果を表示します。
52if ($c14nOutput === false) {
53    echo "エラー: C14Nの実行に失敗しました。\n";
54} else {
55    echo "--- 正規化されたXML (C14N) 結果 ---\n";
56    echo $c14nOutput;
57    echo "\n";
58}
59

このPHPコードは、Dom\HTMLDocumentクラスのC14Nメソッドを使用してXMLコンテンツを正規化する方法を示しています。C14N（Canonical XML）とは、XMLドキュメントの内容を一意の形式に変換する国際標準であり、例えば電子署名などでドキュメントの改ざんがないことを確認する際に重要な役割を果たします。Dom\HTMLDocumentはHTMLを扱いますが、内部的にはXMLと同様のDOMツリーを構築するため、この正規化を適用できます。

サンプルでは、まずHTMLに近いXMLコンテンツを準備し、Dom\HTMLDocumentオブジェクトにロードしています。この際、loadHTML関数のオプションで不要なタグの自動追加を抑制しています。その後、C14Nメソッドを呼び出して正規化を実行します。C14Nメソッドは、XMLの構造をバイト列レベルで比較可能にするために、要素の並び順、属性の形式、名前空間宣言などを標準的な形式に整えます。

メソッドの引数には、排他的正規化を行うかどうかを制御する$exclusive、コメントを出力に含めるかを制御する$with_comments、特定の要素を指定する$xpath、名前空間プレフィックスを指定する$ns_prefixesがありますが、この例ではデフォルト設定で実行しています。成功時には正規化されたXML文字列を返し、失敗時にはfalseを返します。これにより、ドキュメントの等価性を確実に検証できるようになります。

Dom\HTMLDocumentはHTMLをXMLとして内部処理するため、C14N適用時はHTML特有の自動補完挙動に注意が必要です。loadHTMLではLIBXML_HTML_NOIMPLIEDなどのフラグを使い、意図しない要素の追加を防ぐことが重要です。 C14Nメソッドの引数$exclusive（排他的正規化）と$with_comments（コメント含めるか）は、出力内容を大きく変えます。電子署名などで利用する際は、用途に応じてこれらの引数を明示的に指定し、期待通りの出力になるか確認してください。メソッドは失敗時にfalseを返すため、常に戻り値をチェックし、エラーハンドリングを実装することが重要です。これにより、プログラムが安全に動作します。

PHP DOMDocumentをC14N正規化する


1<?php
2
3/**
4 * DOMDocument を C14N 1.1 形式で正規化し、文字列として返します。
5 *
6 * @param DOMDocument $dom ドキュメント
7 * @param bool $exclusive 排他的 C14N を使用するかどうか (デフォルト: false)
8 * @param bool $withComments コメントを含めるかどうか (デフォルト: false)
9 * @param array|null $xpath XPath 式の配列 (デフォルト: null)
10 * @param array|null $nsPrefixes 名前空間プレフィックスの配列 (デフォルト: null)
11 *
12 * @return string|false 正規化された XML 文字列。失敗した場合は false。
13 */
14function canonicalize_dom_document(DOMDocument $dom, bool $exclusive = false, bool $withComments = false, ?array $xpath = null, ?array $nsPrefixes = null): string|false
15{
16    return $dom->C14N($exclusive, $withComments, $xpath, $nsPrefixes);
17}
18
19// 使用例:
20$dom = new DOMDocument();
21$dom->loadXML('<root><child attr="value"/></root>');
22
23$canonicalXml = canonicalize_dom_document($dom);
24
25if ($canonicalXml !== false) {
26    echo $canonicalXml . PHP_EOL;
27} else {
28    echo "C14N failed." . PHP_EOL;
29}

PHPのDom\HTMLDocumentクラスのC14Nメソッドは、XMLドキュメントを正規化された文字列として取得するために使用します。この正規化は、W3Cの「Canonical XML」と呼ばれる標準に基づき、XML文書の内容を論理的に等価な形式に変換することで、異なるシステム間での比較や検証を容易にします。

C14N()メソッドは、引数として排他的C14Nの使用有無($exclusive)、コメントを含めるかどうか($with_comments)、XPath式($xpath)、名前空間プレフィックス($ns_prefixes)を受け取ります。

$exclusiveがtrueの場合、排他的C14Nが適用され、ドキュメントのコンテキスト内で宣言された名前空間のみが保持されます。$with_commentsがtrueの場合、XMLコメントも正規化された文字列に含められます。$xpath引数にXPath式の配列を指定すると、正規化の対象を特定のノードに限定できます。$ns_prefixes引数には、名前空間プレフィックスの配列を渡すことができます。

メソッドは、正規化されたXML文字列を返します。正規化に失敗した場合（例えば、ドキュメントが不正な形式の場合）、falseを返します。サンプルコードでは、canonicalize_dom_document()関数を通じてC14N()メソッドを呼び出し、結果を標準出力に表示しています。正規化されたXMLは、元のXMLドキュメントとは空白や属性の順序などが異なる場合がありますが、意味的には等価です。

Dom\HTMLDocument::C14Nメソッドは、XMLドキュメントをC14N（Canonical XML）形式で正規化します。$exclusive引数をtrueにすると、排他的C14Nが適用され、より厳密な正規化が行われます。$withComments引数をtrueにすると、XMLコメントも出力に含まれます。$xpath引数を使うと、特定のノードセットのみを正規化できます。$nsPrefixes引数は、名前空間プレフィックスを制御するために使用されます。エラーが発生した場合、falseが返されるため、必ず戻り値をチェックしましょう。文字エンコーディングによっては、予期せぬ結果になる可能性があるため、UTF-8での利用を推奨します。XMLの構造によっては、正規化後の出力が変わることに注意してください。