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

Copy
1<?php
2
3/**
4 * DOMノード間の位置比較結果のビットフラグを、可読性のある文字列に変換します。
5 *
6 * @param int $position compareDocumentPositionメソッドから返された整数値
7 * @return string 解釈された位置情報を示す文字列
8 */
9function interpretDocumentPosition(int $position): string
10{
11    $results = [];
12
13    // 両方のノードが同じ位置にある場合 (ビットフラグが設定されていない状態)
14    if ($position === 0) {
15        return 'DOM_DOCUMENT_POSITION_IDENTICAL (0x00)';
16    }
17
18    // 各ビットフラグをチェックし、該当する説明を追加
19    if ($position & DOM_DOCUMENT_POSITION_DISCONNECTED) {
20        $results[] = 'DOM_DOCUMENT_POSITION_DISCONNECTED (0x01): ノードは別のドキュメントまたは接続されていないツリーにある';
21    }
22    if ($position & DOM_DOCUMENT_POSITION_PRECEDING) {
23        $results[] = 'DOM_DOCUMENT_POSITION_PRECEDING (0x02): 比較対象ノードが参照ノードよりも前にある';
24    }
25    if ($position & DOM_DOCUMENT_POSITION_FOLLOWING) {
26        $results[] = 'DOM_DOCUMENT_POSITION_FOLLOWING (0x04): 比較対象ノードが参照ノードよりも後にある';
27    }
28    if ($position & DOM_DOCUMENT_POSITION_CONTAINS) {
29        $results[] = 'DOM_DOCUMENT_POSITION_CONTAINS (0x08): 比較対象ノードが参照ノードを含んでいる';
30    }
31    if ($position & DOM_DOCUMENT_POSITION_CONTAINED_BY) {
32        $results[] = 'DOM_DOCUMENT_POSITION_CONTAINED_BY (0x10): 比較対象ノードが参照ノードに含められている';
33    }
34    if ($position & DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) {
35        $results[] = 'DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC (0x20): 実装固有の動作が発生した';
36    }
37
38    return implode(' | ', $results);
39}
40
41/**
42 * Dom\EntityReference::compareDocumentPosition メソッドの使用例を示します。
43 *
44 * この関数は、PHPDocコメントとPHPの推奨コーディングスタイルに準拠しています。
45 * システムエンジニアを目指す初心者向けに、DOMノード間の相対位置の比較を
46 * 具体的なXML構造と出力を用いて解説します。
47 *
48 * Dom\EntityReference は通常、XML/HTMLドキュメント内で定義されたエンティティ（例: &amp;）
49 * を表すノードですが、PHPのDOM拡張ではパース時に展開されることが多いため、
50 * 明示的に Dom\Document::createEntityReference() で作成してデモを行います。
51 */
52function demonstrateDomEntityReferenceComparison(): void
53{
54    // 新しいDOMドキュメントを作成 (XMLバージョン1.0, UTF-8エンコーディング)
55    $dom = new Dom\Document('1.0', 'UTF-8');
56    // フォーマットを整えることで、XML出力が見やすくなります
57    $dom->formatOutput = true;
58
59    // ルート要素 <root> を作成し、ドキュメントに追加
60    $root = $dom->createElement('root');
61    $dom->appendChild($root);
62
63    // 最初のアイテム要素 <item1> を作成し、ルートに追加
64    $item1 = $dom->createElement('item1');
65    $root->appendChild($item1);
66
67    // テキストノード "Hello " を作成し、<item1> に追加
68    $text1 = $dom->createTextNode('Hello ');
69    $item1->appendChild($text1);
70
71    // エンティティ参照ノード `&amp;` を作成し、<item1> に追加
72    // Dom\EntityReference を直接操作する最も簡単な方法です。
73    // このノードは、ドキュメントにエンティティ宣言がない場合、視覚的には何も表示しませんが、
74    // DOMツリー内のノードとして存在し、比較可能です。
75    $ampEntity = $dom->createEntityReference('amp');
76    $item1->appendChild($ampEntity);
77
78    // テキストノード " World!" を作成し、<item1> に追加
79    $text2 = $dom->createTextNode(' World!');
80    $item1->appendChild($text2);
81
82    // 2番目のアイテム要素 <item2> を作成し、ルートに追加
83    $item2 = $dom->createElement('item2');
84    $root->appendChild($item2);
85    // <item2> にテキストノード "Example" を追加
86    $item2->appendChild($dom->createTextNode('Example'));
87
88    // 現在のDOMツリー構造を出力
89    echo "<h3>DOM Tree Structure:</h3>\n";
90    echo '<pre>' . htmlspecialchars($dom->saveXML()) . "</pre>\n";
91
92    echo "<h3>Comparing Dom\\EntityReference::compareDocumentPosition:</h3>\n";
93
94    // 比較1: エンティティ参照ノードと、その親要素を比較
95    // `$ampEntity` (参照ノード) と `$item1` (比較対象ノード)
96    echo "<h4>1. エンティティ参照ノード ('&amp;') とその親要素 ('<item1>') の比較:</h4>\n";
97    $position = $ampEntity->compareDocumentPosition($item1);
98    echo "  - 結果 (16進数): 0x" . dechex($position) . "\n";
99    echo "  - 解釈: " . interpretDocumentPosition($position) . "\n\n";
100
101    // 比較2: エンティティ参照ノードと、別の兄弟要素を比較
102    // `$ampEntity` (参照ノード) と `$item2` (比較対象ノード)
103    echo "<h4>2. エンティティ参照ノード ('&amp;') と別の要素 ('<item2>') の比較:</h4>\n";
104    $position = $ampEntity->compareDocumentPosition($item2);
105    echo "  - 結果 (16進数): 0x" . dechex($position) . "\n";
106    echo "  - 解釈: " . interpretDocumentPosition($position) . "\n\n";
107
108    // 比較3: エンティティ参照ノードと、その前のテキストノードを比較
109    // `$ampEntity` (参照ノード) と `$text1` (比較対象ノード)
110    echo "<h4>3. エンティティ参照ノード ('&amp;') と前のテキストノード ('Hello ') の比較:</h4>\n";
111    $position = $ampEntity->compareDocumentPosition($text1);
112    echo "  - 結果 (16進数): 0x" . dechex($position) . "\n";
113    echo "  - 解釈: " . interpretDocumentPosition($position) . "\n\n";
114
115    // 比較4: 同じノードを比較
116    // `$ampEntity` (参照ノード) と `$ampEntity` (比較対象ノード)
117    echo "<h4>4. エンティティ参照ノード ('&amp;') とそれ自身との比較:</h4>\n";
118    $position = $ampEntity->compareDocumentPosition($ampEntity);
119    echo "  - 結果 (16進数): 0x" . dechex($position) . "\n";
120    echo "  - 解釈: " . interpretDocumentPosition($position) . "\n\n";
121}
122
123// スクリプトがWebサーバー経由で実行された場合はHTMLとして、CLIから実行された場合はプレーンテキストとして出力
124if (php_sapi_name() === 'cli') {
125    // CLI (コマンドラインインターフェース) で実行された場合
126    // HTMLタグを取り除き、見出しを改行に変換してプレーンテキストとして出力
127    ob_start(); // 出力バッファリングを開始
128    demonstrateDomEntityReferenceComparison();
129    $output = ob_get_clean(); // バッファの内容を取得
130    // HTMLタグを削除し、見出しタグを改行と内容に変換
131    $plainTextOutput = preg_replace_callback(
132        '/<h([1-6])>(.*?)<\/h[1-6]>/',
133        function ($matches) {
134            return "\n" . strtoupper($matches[2]) . "\n" . str_repeat('=', strlen($matches[2])) . "\n";
135        },
136        $output
137    );
138    echo strip_tags($plainTextOutput);
139} else {
140    // Webサーバー経由で実行された場合
141    // HTMLドキュメントとして出力
142    echo "<!DOCTYPE html>\n";
143    echo "<html>\n";
144    echo "<head>\n";
145    echo "    <meta charset=\"UTF-8\">\n";
146    echo "    <title>Dom\\EntityReference::compareDocumentPosition Example</title>\n";
147    echo "</head>\n";
148    echo "<body>\n";
149    demonstrateDomEntityReferenceComparison();
150    echo "</body>\n";
151    echo "</html>\n";
152}

PHPのDom\EntityReference::compareDocumentPositionメソッドは、XMLやHTMLドキュメントのDOMツリーにおいて、二つのノード間の相対的な位置関係を比較するために使用されます。このメソッドは、呼び出し元のノード（参照ノード）と引数で渡されるDom\Node $other（比較対象ノード）の位置関係を調べます。

戻り値は整数値で、これは複数の位置情報を示すビットフラグの組み合わせとなっています。例えば、戻り値が0であれば両方のノードが同じ位置にあることを意味します。その他には、比較対象ノードが参照ノードより前にある、後にある、参照ノードを含んでいる、または参照ノードに含められているといった状態が、DOM_DOCUMENT_POSITION_PRECEDINGやDOM_DOCUMENT_POSITION_CONTAINED_BYのような定数のビット値として返されます。これらの値は論理積演算子（&）を使って個別に判定できます。

サンプルコードでは、最初にXMLドキュメントを作成し、ルート要素、テキストノード、そしてエンティティ参照ノード（&）を追加してDOMツリーを構築しています。その後、作成したエンティティ参照ノードを基準として、その親要素、別の兄弟要素、前のテキストノード、自身といった様々なノードとの位置関係をcompareDocumentPositionメソッドで比較しています。取得した整数値は、別途定義されたinterpretDocumentPosition関数によって、人間が読みやすい文字列に変換されて出力され、各ノード間の具体的な位置関係が明確に示されています。

Copy
1<?php
2
3/**
4 * @brief ドキュメント内のDom\EntityReferenceノードと他のノードの位置を比較するサンプル。
5 *
6 * この関数は、DTDとエンティティ参照を含むXMLドキュメントをパースし、
7 * Dom\EntityReferenceノードを特定して、別のDOMノードとの位置関係を比較します。
8 * 結果はDOM_DOCUMENT_POSITION定数のビットマスクとして返され、
9 * それを解釈して人間が読める形式で表示します。
10 *
11 * @param string $xmlString 比較に使用するXMLドキュメントの文字列。
12 *                          <!DOCTYPE>宣言と<!ENTITY>定義、およびエンティティ参照を含める必要があります。
13 *
14 * @return void 出力は標準出力に行われます。
15 *
16 * @phpdocumentor オプションに関連する DocBlock タグの使用例:
17 * @link https://www.php.net/manual/ja/dom.entityreference.comparedocumentposition.php PHP公式ドキュメントへのリンク
18 * @see Dom\EntityReference::compareDocumentPosition() この関数が利用する主要メソッド。
19 * @category DOM Extension
20 * @package SampleCode
21 */
22function demonstrateEntityReferencePositionComparison(string $xmlString): void
23{
24    $dom = new DOMDocument();
25    // XMLをロード。LIBXML_DTDLOADはDTDをロードするために必要です。
26    // LIBXML_NOENT (エンティティを展開しない) はデフォルトでfalseなので、
27    // エンティティ参照ノードがDOMツリー内に残ります。
28    if (!$dom->loadXML($xmlString, LIBXML_DTDLOAD)) {
29        echo "エラー: XMLのロードに失敗しました。\n";
30        return;
31    }
32
33    $entityRefNode = null;
34    $otherNode = null;
35
36    // ドキュメントツリーを探索し、Dom\EntityReferenceノードと別の比較対象ノードを見つける
37    // ここでは、特定のノード名を仮定して探索しています。
38    $xpath = new DOMXPath($dom);
39    $nodes = $xpath->query('//*'); // ドキュメント内の全ての要素ノードを取得
40
41    foreach ($nodes as $node) {
42        // <item>&myentity;</item> のような構造の場合、&myentity; は <item> の子ノードとして Dom\EntityReference になります。
43        if ($node->nodeName === 'item') {
44            foreach ($node->childNodes as $child) {
45                // 'myentity' はDTDで定義したエンティティの名前です。
46                if ($child instanceof Dom\EntityReference && $child->nodeName === 'myentity') {
47                    $entityRefNode = $child;
48                }
49            }
50        }
51        // 比較対象となる別の要素ノードとして '<other>' を探します。
52        if ($node->nodeName === 'other') {
53            $otherNode = $node;
54        }
55        if ($entityRefNode !== null && $otherNode !== null) {
56            break; // 両方のノードが見つかったら探索を終了
57        }
58    }
59
60    if ($entityRefNode === null) {
61        echo "エラー: Dom\\EntityReference 'myentity' が見つかりませんでした。\n";
62        return;
63    }
64    if ($otherNode === null) {
65        echo "エラー: 比較対象のノード '<other>' が見つかりませんでした。\n";
66        return;
67    }
68
69    echo "--- Dom\\EntityReference::compareDocumentPosition のデモンストレーション ---\n";
70    echo "比較対象1: Dom\\EntityReference (名前: '{$entityRefNode->nodeName}')\n";
71    echo "比較対象2: DOMElement (名前: '{$otherNode->nodeName}')\n";
72
73    /**
74     * compareDocumentPositionの結果ビットマスクを人間が読める文字列に変換するヘルパー関数。
75     *
76     * @param int $position 結果のビットマスク。
77     * @return string 解釈された位置関係。
78     */
79    $interpretPosition = function (int $position): string {
80        $flags = [];
81        if ($position === 0) {
82            return "同一ノード (SAME_NODE)";
83        }
84        if ($position & DOM_DOCUMENT_POSITION_DISCONNECTED) {
85            $flags[] = "切断されています (DISCONNECTED)";
86        }
87        if ($position & DOM_DOCUMENT_POSITION_PRECEDING) {
88            $flags[] = "先行しています (PRECEDING)";
89        }
90        if ($position & DOM_DOCUMENT_POSITION_FOLLOWING) {
91            $flags[] = "後続しています (FOLLOWING)";
92        }
93        if ($position & DOM_DOCUMENT_POSITION_CONTAINS) {
94            $flags[] = "含んでいます (CONTAINS)";
95        }
96        if ($position & DOM_DOCUMENT_POSITION_CONTAINED_BY) {
97            $flags[] = "含まれています (CONTAINED_BY)";
98        }
99        if ($position & DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) {
100            $flags[] = "実装依存 (IMPLEMENTATION_SPECIFIC)";
101        }
102        return implode(" | ", $flags);
103    };
104
105    // Dom\EntityReferenceノードと他のDOMElementノードを比較
106    $comparisonResult = $entityRefNode->compareDocumentPosition($otherNode);
107    echo "比較結果 (ビットマスク): {$comparisonResult}\n";
108    echo "解釈: " . $interpretPosition($comparisonResult) . "\n";
109
110    echo "\n自身と比較した場合:\n";
111    $comparisonResultSelf = $entityRefNode->compareDocumentPosition($entityRefNode);
112    echo "比較結果 (ビットマスク): {$comparisonResultSelf}\n";
113    echo "解釈: " . $interpretPosition($comparisonResultSelf) . "\n";
114}
115
116// --- サンプル実行 ---
117// DTD、エンティティ定義、およびその参照を含むXML文字列
118$sampleXmlContent = <<<XML
119<!DOCTYPE root [
120    <!ENTITY myentity "エンティティの内容">
121]>
122<root>
123    <item>これは<bold>&myentity;</bold>への参照を含むアイテムです。</item>
124    <other>これは他の要素です。</other>
125</root>
126XML;
127
128// 関数を呼び出してサンプルコードを実行します。
129demonstrateEntityReferencePositionComparison($sampleXmlContent);

PHPのDom\EntityReference::compareDocumentPositionメソッドは、XMLドキュメント内のエンティティ参照ノードと、別のDOMノードの相対的な位置関係を比較する際に使用します。Dom\EntityReferenceは、XMLのDTDで定義されたエンティティを参照するノードを指します。

このメソッドは引数として比較対象のDom\Nodeオブジェクトを受け取り、整数値を返します。この戻り値はDOM_DOCUMENT_POSITION定数群のビットマスクであり、両ノードが「先行している」「後続している」「含まれている」といった位置関係を示します。

サンプルコードでは、DTDとエンティティ参照（例: &myentity;）を含むXMLをロードします。LIBXML_DTDLOADオプションを指定することでDTDが読み込まれ、エンティティ参照がDOMツリーに残るようにします。その後、特定のエンティティ参照ノードと別の要素ノードを見つけ出し、compareDocumentPositionメソッドを使ってそれらの位置を比較します。結果のビットマスクは、どの定数が含まれているかを解釈し、人間が読める形式で表示されます。これにより、DOMツリーにおけるノード間の物理的な順序や包含関係をプログラムで正確に把握できます。