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

Copy
1<?php
2
3/**
4 * DOMEntity::C14N() を使用してXMLエンティティを正規化するサンプル関数
5 *
6 * この関数は、DTD(文書型定義)を含むXML文字列を解析し、
7 * 特定のエンティティノードを取得して、その内容を正規化(C14N)します。
8 * 正規化された文字列は、XMLの論理的な意味を保ったまま一貫した形式に変換されるため、
9 * デジタル署名やデータの比較に利用されます。
10 */
11function demonstrateDomEntityC14N(): void
12{
13    // DTDでエンティティが定義されたXML文字列を用意します。
14    // 'myEntity' という名前のエンティティに '<inner>Entity Content</inner>' という内容を定義しています。
15    $xmlString = <<<XML
16<?xml version="1.0" encoding="UTF-8"?>
17<!DOCTYPE root [
18  <!ENTITY myEntity "<inner attr='value'>Entity Content</inner>">
19]>
20<root>
21  <element>&myEntity;</element>
22</root>
23XML;
24
25    // DOMDocumentオブジェクトを生成します。
26    $dom = new DOMDocument();
27
28    // XML文字列を読み込みます。
29    if (!$dom->loadXML($xmlString)) {
30        echo "XMLの読み込みに失敗しました。";
31        return;
32    }
33
34    // ドキュメントのDOCTYPEノードを取得します。
35    $doctype = $dom->doctype;
36
37    // DOCTYPEが存在し、エンティティが定義されているか確認します。
38    if ($doctype && $doctype->entities) {
39        // 'myEntity' という名前のエンティティノード (DOMEntity) を取得します。
40        $entity = $doctype->entities->getNamedItem('myEntity');
41
42        if ($entity instanceof DOMEntity) {
43            // DOMEntityオブジェクトに対して C14N() メソッドを呼び出し、正規化された文字列を取得します。
44            // 失敗した場合は false が返ります。
45            $canonicalizedString = $entity->C14N();
46
47            if ($canonicalizedString !== false) {
48                echo "エンティティ 'myEntity' の正規化 (C14N) された文字列:" . PHP_EOL;
49                echo $canonicalizedString . PHP_EOL;
50            } else {
51                echo "エンティティの正規化に失敗しました。" . PHP_EOL;
52            }
53        } else {
54            echo "エンティティ 'myEntity' が見つかりませんでした。" . PHP_EOL;
55        }
56    } else {
57        echo "DTDまたはエンティティ定義が見つかりませんでした。" . PHP_EOL;
58    }
59}
60
61// サンプル関数を実行します。
62demonstrateDomEntityC14N();
63

DOMEntity::C14N()は、XML文書のDTD（文書型定義）で定義されたエンティティの内容を、W3Cが定める公式ルールに従って「正規化（C14N）」するためのメソッドです。正規化とは、XMLの見た目（例えば属性の順序や空白の量など）が異なっていても、論理的に同じ内容であれば常に同一の文字列に変換する処理のことです。これにより、データの一貫性が保証されるため、デジタル署名やデータの比較などに利用されます。

サンプルコードでは、まずDTD内で<inner>要素を含むmyEntityというエンティティを定義したXML文字列を用意します。次にDOMDocumentオブジェクトでXMLを解析し、getNamedItem()を使って目的のDOMEntityオブジェクトを取得します。そして、そのオブジェクトのC14N()メソッドを呼び出すことで、エンティティの内容が正規化された文字列に変換されます。

このメソッドは、排他的正規化の指定やコメントの有無などを引数で制御できますが、この例では引数を省略し、標準的なルールで処理しています。メソッドは成功すると正規化された文字列を返し、失敗した場合はfalseを返します。サンプルではこの戻り値を確認し、正規化された結果を出力しています。

Copy
1<?php
2
3/**
4 * XML文字列をCanonical XML 1.1 (C14N 1.1) 形式に正規化します。
5 *
6 * Canonical XML (正規化XML) は、空白や属性の順序などが異なる
7 * 論理的に等価な2つのXML文書から、バイト単位で同一の表現を生成するための標準です。
8 * これにより、XMLデータの署名や比較が容易になります。
9 *
10 * @param string $xmlString 正規化するXML文字列
11 * @return string|false 正規化されたXML文字列。失敗した場合は false。
12 */
13function canonicalizeXmlWithC14N11(string $xmlString): string|false
14{
15    // DOMDocumentオブジェクトを作成します。
16    $dom = new DOMDocument();
17
18    // XMLを読み込む際に、不要な空白を保持しないように設定します。
19    $dom->preserveWhiteSpace = false;
20
21    // 与えられたXML文字列をDOMオブジェクトに読み込みます。
22    if (!$dom->loadXML($xmlString)) {
23        // XMLの読み込みに失敗した場合
24        return false;
25    }
26
27    // DOMNode::C14N() メソッドを使用してXML文書を正規化します。
28    // PHP 8.0以降では、第5引数 (mode) に定数を指定することで
29    // 使用する正規化のバージョンを選択できます。
30    //
31    // 引数の説明:
32    // 1. $exclusive:    排他的正規化を行うか (false = 通常の正規化)
33    // 2. $withComments: コメントを含めるか (false = コメントを削除)
34    // 3. $xpath:        正規化対象を絞り込むXPathクエリ (null = 文書全体)
35    // 4. $nsPrefixes:   排他的正規化で利用する名前空間プレフィックスの配列 (null)
36    // 5. $mode:         正規化のバージョン (XML_C14N_1_1 を指定)
37    return $dom->C14N(
38        false,
39        false,
40        null,
41        null,
42        XML_C14N_1_1
43    );
44}
45
46// 正規化対象のXMLデータ
47// 属性の順序がバラバラで、余分な空白や改行、コメントが含まれています。
48$originalXml = <<<XML
49<?xml version="1.0" encoding="UTF-8"?>
50<!-- Sample XML document -->
51<document   status="active" version="1.0" >
52  <message>Hello, C14N 1.1!</message>
53</document>
54XML;
55
56// 関数を呼び出してXMLを正規化します。
57$canonicalizedXml = canonicalizeXmlWithC14N11($originalXml);
58
59if ($canonicalizedXml !== false) {
60    echo "--- Original XML ---" . PHP_EOL;
61    echo $originalXml . PHP_EOL . PHP_EOL;
62
63    echo "--- Canonicalized XML (C14N 1.1) ---" . PHP_EOL;
64    // 出力結果:
65    // <document status="active" version="1.0"><message>Hello, C14N 1.1!</message></document>
66    // コメントや余分な空白が除去され、属性が特定の順序で並び替えられます。
67    echo $canonicalizedXml . PHP_EOL;
68} else {
69    echo "Failed to canonicalize XML." . PHP_EOL;
70}
71

DOMNode::C14N()メソッドは、XML文書を「Canonical XML（正規化XML）」という世界共通の標準形式に変換します。正規化XMLは、属性の記述順や空白の量といった本質的ではない違いを吸収し、論理的に同じ内容を持つXML文書から、常にバイト単位で同一の文字列表現を生成するためのルールです。これにより、XMLデータにデジタル署名を付与したり、二つの文書が同一であるかを厳密に比較したりする際に役立ちます。

このサンプルコードでは、まずXML文字列をDOMDocumentオブジェクトとして読み込み、そのオブジェクトに対してC14N()メソッドを呼び出しています。このメソッドは、第1引数で排他的正規化を行うか、第2引数でコメントを含めるかなどを指定できます。PHP 8.0からは第5引数が追加され、正規化のバージョンを指定できるようになりました。この例ではXML_C14N_1_1定数を渡し、Canonical XML 1.1の仕様で処理を行っています。

メソッドは、処理に成功すると正規化されたXML文字列を返し、失敗した場合はfalseを返します。実行結果を見ると、元のXMLにあったコメントや余分な空白が取り除かれ、属性が特定の順序で整列された、一貫性のある文字列が生成されていることが確認できます。