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

Copy
1<?php
2
3namespace App\DomExamples;
4
5use DOMDocument;
6use DOMElement;
7use DOMText;
8use Dom\CharacterData; // PHP 8で導入されたDom\CharacterDataインターフェース
9use Dom\Node;           // PHP 8で導入されたDom\Nodeインターフェース
10
11/**
12 * Dom\CharacterData::compareDocumentPosition メソッドの使用例を示します。
13 *
14 * このメソッドは、2つのDOMノード間の相対的な位置関係を比較します。
15 * システムエンジニアを目指す初心者向けに、DOMツリー内でのノードの位置を
16 * 理解するための基本的なコードを提供します。
17 *
18 * PHP 8以降では、DOM拡張はDom\NodeおよびDom\CharacterDataインターフェースを導入し、
19 * グローバル名前空間のDOMTextなどのクラスがこれらのインターフェースを実装しています。
20 */
21class DocumentPositionComparator
22{
23    /**
24     * 2つのDOMノード間の位置関係を比較し、結果を分かりやすく表示します。
25     *
26     * compareDocumentPositionメソッドは、DOMツリーにおけるノード間の位置関係を
27     * ビットマスクとして返します。
28     *
29     * @param CharacterData $baseNode    比較の基点となるノード。Dom\CharacterDataを実装している必要があります。
30     * @param Node          $otherNode 比較対象となるもう一方のノード。
31     * @return void
32     */
33    public function compareAndDisplay(CharacterData $baseNode, Node $otherNode): void
34    {
35        echo "--- ノード間の位置関係の比較 ---" . PHP_EOL;
36        echo "基点ノード      : " . $this->getNodeDescription($baseNode) . PHP_EOL;
37        echo "比較対象ノード : " . $this->getNodeDescription($otherNode) . PHP_EOL;
38
39        // Dom\CharacterData インターフェースを実装するノードから
40        // compareDocumentPosition メソッドを呼び出す
41        $result = $baseNode->compareDocumentPosition($otherNode);
42
43        echo "比較結果 (ビットマスク): " . sprintf("0x%02X", $result) . PHP_EOL;
44
45        // 結果の解釈
46        // 結果が0の場合は、2つのノードが同じノードであることを意味します。
47        if ($result === 0) {
48            echo " - 基点ノードと比較対象ノードは同じノードです。" . PHP_EOL;
49        } else {
50            // 各フラグはビットマスクであり、複数の状態を同時に示すことができます。
51            // 論理積 (&) を使って、特定のフラグが立っているかを確認します。
52            if ($result & \DOM_DOCUMENT_POSITION_DISCONNECTED) {
53                echo " - 異なるドキュメントに存在するか、互いに接続されていません。" . PHP_EOL;
54            }
55            if ($result & \DOM_DOCUMENT_POSITION_PRECEDING) {
56                echo " - 比較対象ノードは基点ノードより前にあります (ドキュメント順)。" . PHP_EOL;
57            }
58            if ($result & \DOM_DOCUMENT_POSITION_FOLLOWING) {
59                echo " - 比較対象ノードは基点ノードより後にあります (ドキュメント順)。" . PHP_EOL;
60            }
61            if ($result & \DOM_DOCUMENT_POSITION_CONTAINS) {
62                echo " - 基点ノードは比較対象ノードを含んでいます。" . PHP_EOL;
63            }
64            if ($result & \DOM_DOCUMENT_POSITION_CONTAINED_BY) {
65                echo " - 基点ノードは比較対象ノードに含まれています。" . PHP_EOL;
66            }
67            if ($result & \DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) {
68                echo " - 結果に実装依存のフラグが含まれています。" . PHP_EOL;
69            }
70        }
71        echo PHP_EOL;
72    }
73
74    /**
75     * DOMノードのタイプと内容から説明文字列を生成します。
76     *
77     * @param Node $node 説明を生成するノードインスタンス。
78     * @return string ノードの簡潔な説明。
79     */
80    private function getNodeDescription(Node $node): string
81    {
82        if ($node instanceof DOMText) {
83            $text = trim($node->wholeText);
84            // テキストが長い場合は省略して表示
85            return "DOMText (\"" . (strlen($text) > 30 ? substr($text, 0, 27) . "..." : $text) . "\")";
86        } elseif ($node instanceof DOMElement) {
87            return "DOMElement (<" . $node->tagName . ">)";
88        } else {
89            // その他のDOMノードタイプの場合
90            return get_class($node);
91        }
92    }
93}
94
95// --- 以下はサンプルコードの実行部分です ---
96// この部分は、上記のクラスがどのように使用されるかを示します。
97
98// 1. 新しいDOMドキュメントを作成します。
99$document = new DOMDocument('1.0', 'UTF-8');
100$document->formatOutput = true; // 出力されるXMLを整形します。
101
102// 2. DOMツリーを構築します。
103// ルート要素を作成し、ドキュメントに追加
104$root = $document->createElement('root');
105$document->appendChild($root);
106
107// 子要素とテキストノードを作成
108$parent1 = $document->createElement('parent1');
109$root->appendChild($parent1);
110
111$textA = $document->createTextNode('これはDOMツリー内のテキストAです。');
112$parent1->appendChild($textA);
113
114$textB = $document->createTextNode('これはDOMツリー内のテキストBです。');
115$parent1->appendChild($textB);
116
117$parent2 = $document->createElement('parent2');
118$root->appendChild($parent2);
119
120$textC = $document->createTextNode('これはDOMツリー内のテキストCです。');
121$parent2->appendChild($textC);
122
123// 3. 構築されたDOMツリーのXML表現を出力します（理解の助けに）。
124echo "--- 構築されたDOMツリー ---" . PHP_EOL;
125echo $document->saveXML() . PHP_EOL;
126
127// 4. DocumentPositionComparator クラスのインスタンスを作成します。
128$comparator = new App\DomExamples\DocumentPositionComparator();
129
130// 5. さまざまなノードの組み合わせで比較を実行し、結果を表示します。
131
132// Case 1: 同じノード同士の比較
133// 結果は0（ノードが同じことを示す）になるはずです。
134$comparator->compareAndDisplay($textA, $textA);
135
136// Case 2: 兄弟ノードの比較
137// DOMツリー内の出現順序を比較します。
138$comparator->compareAndDisplay($textA, $textB); // textAの後にtextBが出現
139$comparator->compareAndDisplay($textB, $textA); // textBの前にtextAが出現
140
141// Case 3: 親子関係にあるノードの比較 (基点ノードが子、比較対象ノードが親)
142// $textA は $parent1 に含まれています。
143$comparator->compareAndDisplay($textA, $parent1);
144
145// Case 4: 親子関係にあるノードの比較 (基点ノードが子、比較対象ノードがさらに上位の親)
146// $textA は $root にも含まれています。
147$comparator->compareAndDisplay($textA, $root);
148
149// Case 5: 異なるブランチ（枝）のノードの比較
150// ドキュメント順での位置関係を比較します。
151$comparator->compareAndDisplay($textA, $textC); // textAの後にtextCが出現
152$comparator->compareAndDisplay($textC, $textA); // textCの前にtextAが出現
153
154// Case 6: 接続されていないノード（異なるドキュメント、またはどのドキュメントにも属さない）の比較
155$disconnectedDoc = new DOMDocument();
156$disconnectedText = $disconnectedDoc->createTextNode('これはどのDOMツリーにも接続されていません。');
157// $textAが属するドキュメントと、$disconnectedTextが属するドキュメントは異なります。
158$comparator->compareAndDisplay($textA, $disconnectedText);

PHP 8で導入されたDom\CharacterData::compareDocumentPositionメソッドは、DOMツリー内の二つのノードがどのような位置関係にあるかを比較するための機能です。このメソッドは、Dom\Node $otherという引数に比較したい別のノードを受け取ります。そして、二つのノードの位置関係を示す整数値（ビットマスク）をint型で返します。この戻り値は、ノードが同じであるか、互いに含まれているか、ドキュメントの順序で前にあるか後にあるかなど、複数の状態を同時に表現します。

サンプルコードは、まずXMLドキュメントの構造を模したDOMツリーを構築します。その後、構築されたDOMツリーから様々なノードの組み合わせを選び、compareDocumentPositionメソッドを使用してそれらのノード間の位置関係を具体的に比較します。例えば、同じノード同士の比較、親子関係にあるノードの比較、兄弟ノードの比較、さらには異なるドキュメントに属するノードの比較など、多様なシナリオで結果を表示します。これにより、初心者の方でもメソッドが返すビットマスクが実際にどのような意味を持つのか、視覚的に理解できるようになっています。このメソッドは、DOM操作においてノードの相対的な位置を正確に把握する際に非常に役立ちます。

Copy
1<?php
2
3// PHP 8.2以降ではこれらの定数は組み込みですが、それ以前のバージョンとの互換性のため定義します。
4if (!defined('DOM_DOCUMENT_POSITION_DISCONNECTED')) {
5    define('DOM_DOCUMENT_POSITION_DISCONNECTED', 0x01);
6    define('DOM_DOCUMENT_POSITION_PRECEDING', 0x02);
7    define('DOM_DOCUMENT_POSITION_FOLLOWING', 0x04);
8    define('DOM_DOCUMENT_POSITION_CONTAINS', 0x08);
9    define('DOM_DOCUMENT_POSITION_CONTAINED_BY', 0x10);
10    define('DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC', 0x20);
11}
12
13/**
14 * Dom\CharacterData::compareDocumentPosition メソッドの使用例を示します。
15 * このメソッドは、2つのノード間の相対位置関係をビットマスクとして返します。
16 *
17 * phpdocumentor のようなドキュメンテーションツールは、このようなビットマスクの戻り値について、
18 * 各ビットが何を表すかの「オプション」情報を提供することが期待されます。
19 * このサンプルコードでは、その期待に応える形で、戻り値の各ビットフラグの意味を詳細に解説します。
20 */
21function demonstrateCompareDocumentPosition(): void
22{
23    // 1. ドキュメントツリーの準備
24    $dom = new Dom\Document('1.0', 'UTF-8');
25    $dom->formatOutput = true; // 出力を見やすくするための設定
26
27    $root = $dom->createElement('root');
28    $dom->appendChild($root);
29
30    $parent = $dom->createElement('parent');
31    $root->appendChild($parent);
32
33    // 基準となるノード (Dom\CharacterDataの子クラスであるDom\Textノード)
34    $textNodeA = $dom->createTextNode('基準テキスト');
35    $parent->appendChild($textNodeA); // textNodeA は parent の子ノード
36
37    // 基準ノードの後続にあるテキストノード
38    $textNodeB = $dom->createTextNode('後続テキスト');
39    $parent->appendChild($textNodeB);
40
41    // 基準ノードとは別のブランチにある要素ノード (同じドキュメント内)
42    $siblingElement = $dom->createElement('sibling');
43    $root->appendChild($siblingElement);
44
45    // 別のドキュメントのノード (完全に分離されている)
46    $anotherDom = new Dom\Document();
47    $unrelatedElement = $anotherDom->createElement('unrelated');
48    $anotherDom->appendChild($unrelatedElement);
49
50    echo "--- 基準ノード: '{$textNodeA->nodeValue}' (Dom\\Text) ---\n";
51
52    /**
53     * ノードを比較し、結果を詳細に表示するヘルパー関数。
54     *
55     * @param Dom\CharacterData $nodeA 比較の基準となるノード
56     * @param Dom\Node $nodeB 比較対象のノード
57     * @param string $description 比較対象ノードの説明
58     */
59    $compareAndPrint = function (Dom\CharacterData $nodeA, Dom\Node $nodeB, string $description) {
60        $position = $nodeA->compareDocumentPosition($nodeB);
61
62        echo "\n比較対象: {$description}\n";
63        echo "  結果のビットマスク (int): {$position}\n";
64        echo "  意味:\n";
65
66        // ここから、phpdocumentor の「オプション」として考えられる、
67        // 戻り値のビットマスクの詳細な解説を行います。
68        if ($position === 0) {
69            echo "    両ノードが同じです。\n";
70        } else {
71            if ($position & DOM_DOCUMENT_POSITION_DISCONNECTED) {
72                echo "    DOM_DOCUMENT_POSITION_DISCONNECTED (0x01): 両ノードは同じドキュメントツリー内にありません。\n";
73            }
74            if ($position & DOM_DOCUMENT_POSITION_PRECEDING) {
75                echo "    DOM_DOCUMENT_POSITION_PRECEDING (0x02): 比較対象ノードが基準ノードの前に現れます。\n";
76            }
77            if ($position & DOM_DOCUMENT_POSITION_FOLLOWING) {
78                echo "    DOM_DOCUMENT_POSITION_FOLLOWING (0x04): 比較対象ノードが基準ノードの後に現れます。\n";
79            }
80            if ($position & DOM_DOCUMENT_POSITION_CONTAINS) {
81                echo "    DOM_DOCUMENT_POSITION_CONTAINS (0x08): 基準ノードが比較対象ノードを含んでいます。\n";
82            }
83            if ($position & DOM_DOCUMENT_POSITION_CONTAINED_BY) {
84                echo "    DOM_DOCUMENT_POSITION_CONTAINED_BY (0x10): 基準ノードが比較対象ノードに含まれています。\n";
85            }
86            if ($position & DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) {
87                echo "    DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC (0x20): 実装固有の動作が発生しました。\n";
88            }
89        }
90    };
91
92    // 2. 様々なノードとの比較を実行
93    // 基準ノード自身との比較
94    $compareAndPrint($textNodeA, $textNodeA, "基準ノード自身 ('{$textNodeA->nodeValue}')");
95
96    // 後続のノードとの比較
97    $compareAndPrint($textNodeA, $textNodeB, "後続のテキストノード ('{$textNodeB->nodeValue}')");
98
99    // 親要素との比較 (基準ノードは親要素に含まれている)
100    $compareAndPrint($textNodeA, $parent, "親要素 ('<parent>')");
101
102    // 別のブランチにある要素との比較 (同じドキュメント内だが、異なる階層)
103    $compareAndPrint($textNodeA, $siblingElement, "同じルートの子ノード ('<sibling>')");
104
105    // 別のドキュメントのノードとの比較 (完全に分離)
106    $compareAndPrint($textNodeA, $unrelatedElement, "別のドキュメントのノード ('<unrelated>')");
107}
108
109// サンプルコードの実行
110demonstrateCompareDocumentPosition();

PHPのDom\CharacterData::compareDocumentPositionメソッドは、XMLやHTMLドキュメント内で2つのノードがどのような相対的な位置関係にあるかを比較するための機能です。

このメソッドは、引数として比較対象となる別のDom\Nodeを受け取ります。戻り値は整数値（int）のビットマスクであり、これは複数の位置関係を示すフラグの組み合わせとして解釈されます。

具体的には、戻り値が0の場合は両方のノードが同一であることを示します。それ以外の値の場合、例えば、比較対象ノードが基準ノードとは別のドキュメントツリーにある場合はDOM_DOCUMENT_POSITION_DISCONNECTED、基準ノードの前に現れる場合はDOM_DOCUMENT_POSITION_PRECEDING、後に現れる場合はDOM_DOCUMENT_POSITION_FOLLOWING、基準ノードが比較対象ノードを含んでいる場合はDOM_DOCUMENT_POSITION_CONTAINS、含まれている場合はDOM_DOCUMENT_POSITION_CONTAINED_BYといったフラグが返されます。これらのフラグは排他的ではなく、同時に複数設定されることがあります。

サンプルコードでは、まず基準となるテキストノードを作成し、それに対して様々な位置にあるノード（親ノード、兄弟ノード、別のドキュメントのノードなど）をcompareDocumentPositionメソッドで比較しています。そして、戻り値のビットマスクをPHPの定数とビット演算で照合し、各フラグが実際にどのような状況で設定されるかを詳細に示しています。これにより、ドキュメント操作の際にノード間の複雑な位置関係を正確に判断する方法を理解できます。