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

Copy
1<?php
2
3// XMLドキュメントの正規化 (C14N) を示すサンプルコードです。
4// C14Nは、XMLドキュメントの標準的なバイト表現を生成するために使用されます。
5// これにより、論理的に同じXMLドキュメントが、異なるシリアル化方法によっても常に同じバイト列に変換され、
6// 比較や署名検証などが容易になります。
7function demonstrateDomElementC14n(): void
8{
9    // 正規化対象のXML文字列を定義します。
10    // コメントや属性の順序など、C14Nによって正規化される要素を含めます。
11    $xmlString = <<<XML
12<root id="main" xmlns:app="http://example.com/app">
13    <!-- このコメントはC14Nの挙動に影響を与えます -->
14    <child name="itemA" value="123">
15        <grandchild property="X"/>
16    </child>
17    <child value="456" name="itemB"/>
18</root>
19XML;
20
21    // DOMDocumentインスタンスを作成し、XMLをロードします。
22    $dom = new DOMDocument();
23    // loadXMLが失敗する可能性を考慮しますが、このサンプルでは簡潔さのためエラーチェックは最小限にします。
24    if (! $dom->loadXML($xmlString)) {
25        echo "Error: Failed to load XML.\n";
26        return;
27    }
28
29    // Dom\ElementクラスのC14Nメソッドを使用するため、DomDocumentのルート要素を取得します。
30    // DOMDocument::documentElement は Dom\Element (またはそのサブクラス) のインスタンスを返します。
31    $element = $dom->documentElement;
32
33    // 取得した要素がDom\Elementのインスタンスであることを確認します。
34    if (! $element instanceof Dom\Element) {
35        echo "Error: Document element is not an instance of Dom\\Element.\n";
36        return;
37    }
38
39    echo "--- オリジナルXML --- \n";
40    echo $xmlString . "\n\n";
41
42    // 1. デフォルトのC14Nを適用します。
43    // 引数なしの場合、または第一引数`false`、第二引数`false`（デフォルト値）を指定した場合、
44    // コメントは出力に含まれません。属性はアルファベット順にソートされ、名前空間宣言も正規化されます。
45    $c14nDefault = $element->C14N();
46
47    if ($c14nDefault !== false) {
48        echo "--- C14N (デフォルト: コメントなし) --- \n";
49        echo $c14nDefault . "\n\n";
50    } else {
51        echo "Error: C14N (default) 失敗しました。\n\n";
52    }
53
54    // 2. コメントを含むC14Nを適用します。
55    // 第二引数 `$withComments` を `true` に設定することで、XMLコメントも正規化された出力に含まれます。
56    $c14nWithComments = $element->C14N(false, true); // $exclusive = false, $withComments = true
57
58    if ($c14nWithComments !== false) {
59        echo "--- C14N (コメントあり) --- \n";
60        echo $c14nWithComments . "\n\n";
61    } else {
62        echo "Error: C14N (with comments) 失敗しました。\n\n";
63    }
64}
65
66// 関数を実行します。
67demonstrateDomElementC14n();

Dom\Element::C14Nメソッドは、XMLドキュメントを「正規化（Canonicalization）」するための機能を提供します。これは、XMLドキュメントが異なる方法で記述されていても、論理的に同じ内容であれば常に同じ標準的なバイト表現に変換されるようにすることで、XMLの比較や電子署名の検証を確実に行えるようにします。

このメソッドを使用するには、まずDOMDocumentクラスでXMLをロードし、そこから正規化したい要素をDom\Elementインスタンスとして取得する必要があります。

C14N()メソッドを引数なしで呼び出すか、第一引数$exclusiveをfalse、第二引数$withCommentsをfalse（デフォルト値）で呼び出すと、XMLコメントを含まない形式で正規化されます。この際、属性はアルファベット順にソートされ、名前空間の宣言も標準的な形式に整えられます。

第二引数$withCommentsをtrueに設定すると、元のXMLドキュメントに含まれるコメントも正規化された出力に含まれるようになります。第一引数$exclusiveは、名前空間の扱いを制御するためのもので、通常はデフォルトのfalse（非排他的C14N）を使用します。

メソッドが成功すると、正規化されたXMLを表す文字列が返されます。もし正規化処理が失敗した場合はfalseが返されるため、戻り値の確認は重要です。このC14Nメソッドは、XMLベースのセキュリティやデータ連携において、文書の一貫性を保証するために不可欠なツールです。

Copy
1<?php
2
3/**
4 * XML要素を正規化(C14N)するサンプルコード
5 *
6 * Dom\Element::C14N()メソッドを使用して、特定のXML要素を
7 * Canonical XML (C14N) 形式の文字列に変換します。
8 *
9 * @return void
10 */
11function generateCanonicalXmlElement(): void
12{
13    // サンプルとなるXML文字列を定義します。
14    // 属性の順序が異なったり、余分な空白があったりします。
15    $xmlString = <<<XML
16<?xml version="1.0" encoding="UTF-8"?>
17<root xmlns:dc="http://purl.org/dc/elements/1.1/">
18  <book   author="Gambardella, Matthew"   id="bk101" >
19    <title>XML Developer's Guide</title>
20    <!-- これは正規化時に削除されるコメントです -->
21    <dc:creator>Matthew Gambardella</dc:creator>
22  </book>
23  <book id="bk102" author="Ralls, Kim">
24    <title>Midnight Rain</title>
25  </book>
26</root>
27XML;
28
29    // DOMDocumentオブジェクトを作成し、XMLを読み込みます。
30    $dom = new DOMDocument();
31    $dom->loadXML($xmlString);
32
33    // 正規化の対象となる最初の<book>要素を取得します。
34    // getElementsByTagNameはDOMNodeListを返すため、item(0)で最初の要素を指定します。
35    $bookElement = $dom->getElementsByTagName('book')->item(0);
36
37    // 取得した要素がDOMElementであることを確認します。
38    if (!$bookElement instanceof DOMElement) {
39        echo 'Error: Could not find the <book> element.' . PHP_EOL;
40        return;
41    }
42
43    // Dom\Element::C14N() を使って要素を正規化します。
44    // 第1引数(exclusive): 排他的正規化を行うかどうか (デフォルト: false)
45    // 第2引数(withComments): コメントを含めるかどうか (デフォルト: false)
46    //
47    // C14N (Canonicalization) とは、論理的に同じXML文書が
48    // 常に同じバイト表現になるように変換するプロセスです。
49    // これにより、デジタル署名などでXML文書を確実に比較できます。
50    $canonicalXmlString = $bookElement->C14N(false, false);
51
52    if ($canonicalXmlString !== false) {
53        echo "--- Original First <book> Element (as string) ---" . PHP_EOL;
54        echo $dom->saveXML($bookElement) . PHP_EOL;
55
56        echo PHP_EOL;
57
58        echo "--- Canonicalized (C14N) <book> Element ---" . PHP_EOL;
59        echo $canonicalXmlString . PHP_EOL;
60    } else {
61        echo "Failed to generate C14N for the element." . PHP_EOL;
62    }
63}
64
65// 関数を実行します。
66generateCanonicalXmlElement();

Dom\Element::C14N()は、特定のXML要素を「正規化（C14N）」し、一意の文字列表現に変換するためのメソッドです。正規化とは、属性の順序、不要な空白、コメントといった記述方法の違いを吸収し、論理的に同じ内容を持つXMLが必ず同一の文字列になるように整える処理を指します。これにより、XML文書の比較やデジタル署名の検証を正確に行うことができます。

このサンプルコードでは、まずXML文字列をDOMDocumentオブジェクトとして読み込み、getElementsByTagName()で最初の<book>要素を取得しています。次に、取得したDom\ElementオブジェクトのC14N()メソッドを呼び出し、要素を正規化します。

第1引数の$exclusiveは排他的正規化を行うか、第2引数の$withCommentsはコメントを出力に含めるかを真偽値で指定します。この例では両方にfalseが指定されているため、コメントは除去されます。メソッドは、処理に成功すると正規化されたXML文字列を返し、失敗した場合はfalseを返します。実行すると、元のXMLからコメントと余分な空白が取り除かれ、属性が統一された順序で出力されることが確認できます。