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

Copy
1<?php
2
3// このファイルは単体で動作します。
4// システムエンジニアを目指す初心者の方へ：
5// ここに記述されているPHPDocコメントは、phpDocumentorのようなツールで
6// プロジェクトのドキュメントを自動生成する際に活用されます。
7// また、`namespace App\DomUtil;` のような名前空間の利用は、
8// Composerを使った依存関係管理とオートロードの基本的な構成要素です。
9
10namespace App\DomUtil;
11
12/**
13 * DOMノード間の位置関係を比較するユーティリティクラス。
14 *
15 * このクラスは、DOMツリー内でのノードの相対的な位置を比較するメソッドを提供します。
16 * 特にDOMTextノード間の比較に焦点を当てていますが、
17 * `DOMNode::compareDocumentPosition()` メソッドは任意の `DOMNode` オブジェクト間で利用可能です。
18 * PHPの推奨コーディングスタイルに従い、可読性と保守性を高めています。
19 */
20class DomComparator
21{
22    /**
23     * 2つのDOMノードの文書内での位置関係を比較し、その結果を人間が読める形式で返します。
24     *
25     * `DOMNode::compareDocumentPosition()` メソッドは、2つのノードの相対的な位置を
26     * ビットマスクとして返します。このメソッドは、そのビットマスクを解釈し、
27     * 初心者にも分かりやすい説明を生成します。
28     *
29     * @param \DOMNode $nodeA 比較する最初のDOMノード
30     * @param \DOMNode $nodeB 比較する2番目のDOMノード
31     * @return string 比較結果を説明する文字列
32     * @link https://www.php.net/manual/ja/domnode.comparedocumentposition.php PHP Manual for compareDocumentPosition
33     */
34    public function describeNodePosition(\DOMNode $nodeA, \DOMNode $nodeB): string
35    {
36        // DOMNode::compareDocumentPosition() メソッドを呼び出し、位置フラグを取得します。
37        // リファレンスにあるように、DOMTextオブジェクトもDOMNodeを継承しているので、
38        // このメソッドから呼び出すことができます。
39        $positionFlags = $nodeA->compareDocumentPosition($nodeB);
40
41        $description = [];
42
43        // 同じノードである場合は、他のフラグは立たないため最初にチェックします。
44        if ($positionFlags === 0) {
45            $description[] = '同じノードです。';
46            return implode(', ', $description);
47        }
48
49        // 各ビットフラグをチェックし、該当する説明を追加します。
50        // PHPのDOM拡張には、これらの定数が用意されています。
51        if ($positionFlags & \DOM_DOCUMENT_POSITION_DISCONNECTED) {
52            $description[] = '分離しています (異なるドキュメントに属するか、ドキュメントツリーに接続されていない)';
53        }
54        if ($positionFlags & \DOM_DOCUMENT_POSITION_PRECEDING) {
55            $description[] = '先行しています (ノードBがノードAより前に位置する)';
56        }
57        if ($positionFlags & \DOM_DOCUMENT_POSITION_FOLLOWING) {
58            $description[] = '後続しています (ノードBがノードAより後に位置する)';
59        }
60        if ($positionFlags & \DOM_DOCUMENT_POSITION_CONTAINS) {
61            $description[] = '内包しています (ノードAがノードBを含む親/祖先ノードである)';
62        }
63        if ($positionFlags & \DOM_DOCUMENT_POSITION_CONTAINED_BY) {
64            $description[] = '内包されています (ノードBがノードAを含む親/祖先ノードである)';
65        }
66        if ($positionFlags & \DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) {
67            $description[] = '実装依存の比較結果です';
68        }
69
70        // 何も該当しない場合は、通常は上記のどれかに該当するはずですが、念のため。
71        if (empty($description)) {
72            return '不明な位置関係です。';
73        }
74
75        return implode(', ', $description);
76    }
77}
78
79// --- 以下は、上記クラスの具体的な利用例です ---
80
81// DomComparatorクラスのインスタンスを作成します。
82// 実際のComposerプロジェクトでは、'use App\DomUtil\DomComparator;' のように
83// 名前空間を使ってクラスをロードしますが、この例では同じファイル内にあるため、
84// 完全修飾名で直接インスタンス化しています。
85$comparator = new App\DomUtil\DomComparator();
86
87// DOMDocumentオブジェクトを作成し、HTML構造を構築します。
88$dom = new \DOMDocument('1.0', 'UTF-8');
89$dom->formatOutput = true; // 出力されるHTMLを見やすく整形する設定
90
91$root = $dom->createElement('div');
92$root->setAttribute('id', 'root');
93$dom->appendChild($root);
94
95$p1 = $dom->createElement('p');
96$textA = $dom->createTextNode('最初の'); // textA (DOMTextノード)
97$p1->appendChild($textA);
98$root->appendChild($p1);
99
100$span = $dom->createElement('span');
101$textB = $dom->createTextNode('中間'); // textB (DOMTextノード)
102$span->appendChild($textB);
103$p1->appendChild($span); // <p>最初の<span>中間</span></p>
104
105$textC = $dom->createTextNode('テキスト'); // textC (DOMTextノード)
106$p1->appendChild($textC); // <p>最初の<span>中間</span>テキスト</p>
107
108$p2 = $dom->createElement('p');
109$textD = $dom->createTextNode('最後の'); // textD (DOMTextノード)
110$p2->appendChild($textD);
111$root->appendChild($p2);
112
113// ドキュメントツリーに属さないDOMTextノードを作成
114$detachedText = $dom->createTextNode('分離された');
115
116echo "--- DOMText::compareDocumentPosition メソッド利用例 ---\n\n";
117echo "構築されたDOM構造のHTML表現:\n" . htmlspecialchars($dom->saveHTML()) . "\n\n";
118
119// 比較1: textA ('最初の') と textB ('中間')
120// DOMツリー上では、textBはtextAの後ろに位置します。
121echo "1. textA ('{$textA->wholeText}') と textB ('{$textB->wholeText}') の比較:\n";
122echo "   結果: " . $comparator->describeNodePosition($textA, $textB) . "\n";
123echo "   (期待値: 後続しています)\n\n";
124
125// 比較2: textB ('中間') と textA ('最初の')
126// textAはtextBの前に位置します。
127echo "2. textB ('{$textB->wholeText}') と textA ('{$textA->wholeText}') の比較:\n";
128echo "   結果: " . $comparator->describeNodePosition($textB, $textA) . "\n";
129echo "   (期待値: 先行しています)\n\n";
130
131// 比較3: textA ('最初の') と textC ('テキスト')
132// textCはtextAと同じ親の子であり、textAの後に位置します。
133echo "3. textA ('{$textA->wholeText}') と textC ('{$textC->wholeText}') の比較:\n";
134echo "   結果: " . $comparator->describeNodePosition($textA, $textC) . "\n";
135echo "   (期待値: 後続しています)\n\n";
136
137// 比較4: textA と textA (同じノード)
138echo "4. textA ('{$textA->wholeText}') と自身 ('{$textA->wholeText}') の比較:\n";
139echo "   結果: " . $comparator->describeNodePosition($textA, $textA) . "\n";
140echo "   (期待値: 同じノードです。)\n\n";
141
142// 比較5: textA ('最初の') と detachedText ('分離された')
143// detachedTextはどのDOMツリーにも接続されていないため、分離状態と見なされます。
144echo "5. textA ('{$textA->wholeText}') とドキュメントに属さないノード ('{$detachedText->wholeText}') の比較:\n";
145echo "   結果: " . $comparator->describeNodePosition($textA, $detachedText) . "\n";
146echo "   (期待値: 分離しています)\n\n";
147
148// 比較6: textA ('最初の') と root要素 (`<div>`)
149// `DOMNode::compareDocumentPosition()` は `DOMText` だけでなく、任意の `DOMNode` (例えば `DOMElement`) との比較も可能です。
150// root要素はtextAを含む親ノードであるため、「内包されている」という関係になります。
151echo "6. textA ('{$textA->wholeText}') と root要素 ('{$root->nodeName}') の比較:\n";
152echo "   結果: " . $comparator->describeNodePosition($textA, $root) . "\n";
153echo "   (期待値: 内包されています - rootがtextAを含む親ノードである)\n\n";
154
155// 比較7: root要素 (`<div>`) と textA ('最初の')
156// root要素から見ると、textAを内包しています。
157echo "7. root要素 ('{$root->nodeName}') と textA ('{$textA->wholeText}') の比較:\n";
158echo "   結果: " . $comparator->describeNodePosition($root, $textA) . "\n";
159echo "   (期待値: 内包しています - rootがtextAを含む親ノードである)\n\n";

DOMText::compareDocumentPositionメソッドは、DOMツリー上にある2つのノードが互いにどのような位置関係にあるかを判定するために利用されます。このメソッドはDOMTextクラスに属しますが、実際にはDOMNodeを継承する任意のノード間で比較が可能です。引数には比較対象となるもう一方のDOMNodeオブジェクトを一つ指定します。戻り値は整数値で、これは複数の位置関係を同時に表すビットマスクとして返されます。例えば、ノードが同じであるか、先行しているか、後続しているか、互いに内包しているか、またはドキュメントツリーから分離しているかといった詳細な情報を取得できます。

提供されたサンプルコードでは、このビットマスクの戻り値を解釈し、「先行しています」「内包されています」といった人間が理解しやすい文字列に変換して表示するDomComparatorクラスが実装されています。このコードは、PHPDocコメントを通じてphpDocumentorのようなツールでドキュメントを自動生成する際の基盤となり、namespaceの利用はComposerによる依存管理とオートロードの仕組みに不可欠です。本メソッドは、WebアプリケーションでDOMを動的に操作する際に、ノードの正確な配置を把握し、複雑な処理を実装するために非常に役立ちます。

Copy
1<?php
2
3/**
4 * DOMノードの位置関係を比較し、その結果を分かりやすい文字列で表示します。
5 *
6 * この関数は、DOMText::compareDocumentPosition メソッドの戻り値であるビットマスクを解析し、
7 * 各ビットが示す意味を人間が理解しやすい形式で出力します。
8 * DOM_DOCUMENT_POSITION_* 定数に基づいた具体的な情報を提供し、
9 * システムエンジニアを目指す初心者の方にも結果が直感的にわかるように設計されています。
10 *
11 * @param int $result DOMText::compareDocumentPosition メソッドの戻り値 (ビットマスク)
12 * @param string $nodeName1 比較元ノードの名前 (表示用)
13 * @param string $nodeName2 比較対象ノードの名前 (表示用)
14 * @return void 結果を標準出力に出力します
15 */
16function displayComparisonResult(int $result, string $nodeName1, string $nodeName2): void
17{
18    echo "--- 比較結果: {$nodeName1} と {$nodeName2} ---\n";
19
20    // 戻り値が0の場合、ノードは同じであるか、エラー状態を示します。
21    // compareDocumentPosition は同じノードを比較すると通常0を返します。
22    if ($result === 0) {
23        echo "- ノードは同じです。\n";
24        echo "\n";
25        return;
26    }
27
28    // 各定数に対応するビットが立っているかチェックし、意味を表示します。
29    if ($result & DOM_DOCUMENT_POSITION_DISCONNECTED) {
30        echo "- 互いに異なるサブツリーにあります (DOM_DOCUMENT_POSITION_DISCONNECTED)\n";
31    }
32    if ($result & DOM_DOCUMENT_POSITION_PRECEDING) {
33        echo "- {$nodeName1} は {$nodeName2} の前に位置します (DOM_DOCUMENT_POSITION_PRECEDING)\n";
34    }
35    if ($result & DOM_DOCUMENT_POSITION_FOLLOWING) {
36        echo "- {$nodeName1} は {$nodeName2} の後に位置します (DOM_DOCUMENT_POSITION_FOLLOWING)\n";
37    }
38    if ($result & DOM_DOCUMENT_POSITION_CONTAINS) {
39        echo "- {$nodeName1} は {$nodeName2} を含んでいます (DOM_DOCUMENT_POSITION_CONTAINS)\n";
40    }
41    if ($result & DOM_DOCUMENT_POSITION_CONTAINED_BY) {
42        echo "- {$nodeName1} は {$nodeName2} に含まれています (DOM_DOCUMENT_POSITION_CONTAINED_BY)\n";
43    }
44    if ($result & DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) {
45        echo "- 実装固有の何らかの関係があります (DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC)\n";
46    }
47    echo "\n";
48}
49
50// 1. DOMDocument オブジェクトを作成し、HTML構造を構築します。
51// これは、DOMノードを比較するための基盤となります。
52$dom = new DOMDocument('1.0', 'UTF-8');
53$dom->formatOutput = true; // 出力されるHTMLを見やすく整形します
54
55// ルート要素 (html) を作成し、ドキュメントに追加
56$html = $dom->createElement('html');
57$dom->appendChild($html);
58
59// body要素を作成し、html要素に追加
60$body = $dom->createElement('body');
61$html->appendChild($body);
62
63// 最初の段落 (p1) を作成し、body要素に追加
64$p1 = $dom->createElement('p');
65$p1->setAttribute('id', 'paragraph1');
66$body->appendChild($p1);
67
68// p1 の中に最初のテキストノードを作成
69$text1 = $dom->createTextNode('これは最初のテキストです。');
70$p1->appendChild($text1);
71
72// p1 の中にspan要素とそのテキストノードを作成
73$span = $dom->createElement('span', 'スパン内のテキスト。');
74$p1->appendChild($span);
75
76// p1 の中に2番目のテキストノードを作成
77$text2 = $dom->createTextNode('これは2番目のテキストです。');
78$p1->appendChild($text2);
79
80// 2番目の段落 (p2) を作成し、body要素に追加
81$p2 = $dom->createElement('p');
82$p2->setAttribute('id', 'paragraph2');
83$body->appendChild($p2);
84
85// p2 の中に3番目のテキストノードを作成
86$text3 = $dom->createTextNode('これは独立したテキストです。');
87$p2->appendChild($text3);
88
89// DOMツリーの完成。ここからノードの比較を行います。
90echo "--- DOMText::compareDocumentPosition の使用例 ---\n\n";
91
92// 例1: 同じ親要素内の異なるテキストノードを比較
93// text1 は text2 の物理的な文書順で前に位置します。
94$result1 = $text1->compareDocumentPosition($text2);
95displayComparisonResult($result1, 'text1', 'text2');
96
97// 例2: 順序を逆にして比較
98// text2 は text1 の物理的な文書順で後に位置します。
99$result2 = $text2->compareDocumentPosition($text1);
100displayComparisonResult($result2, 'text2', 'text1');
101
102// 例3: 異なる親要素内のテキストノードを比較
103// text1 と text3 は異なるサブツリーにあり、text1 は text3 の文書順で前に位置します。
104$result3 = $text1->compareDocumentPosition($text3);
105displayComparisonResult($result3, 'text1', 'text3');
106
107// 例4: 親要素と子要素のテキストノードを比較
108// DOMNode を引数に取るため、DOMText 以外のノードとも比較可能です。
109// p1 (DOMElement) は text1 (DOMText) を含んでいます。
110$result4 = $p1->compareDocumentPosition($text1);
111displayComparisonResult($result4, 'p1 (DOMElement)', 'text1 (DOMText)');
112
113// 例5: 子要素と親要素を比較
114// text1 (DOMText) は p1 (DOMElement) に含まれています。
115$result5 = $text1->compareDocumentPosition($p1);
116displayComparisonResult($result5, 'text1 (DOMText)', 'p1 (DOMElement)');
117
118?>

PHPのDOMText::compareDocumentPositionメソッドは、DOMツリー内の二つのノード間の相対的な位置関係を比較します。このメソッドは、呼び出し元のDOMTextノードと、引数$other (DOMNode型) の位置関係を分析します。

戻り値は整数（int）のビットマスクで、複数の情報を含みます。ノードが互いに異なるサブツリーにあるか、文書順で前か後か、あるいは含むか含まれるかといった関係を、DOM_DOCUMENT_POSITION_DISCONNECTEDやDOM_DOCUMENT_POSITION_PRECEDINGといったDOM_DOCUMENT_POSITION_*定数に対応するビットの組み合わせで表現します。

サンプルコードは、このビットマスクを解析し、システムエンジニアを目指す初心者にも分かりやすい形で結果を表示し、メソッドの挙動を解説しています。テキストノード間の順序や親子関係など、多様なDOMノード間の位置関係を正確に判断できることが示されています。この機能は、Webコンテンツの解析や動的な要素操作において、ノードの相対的な位置をプログラムで判断する上で非常に役立ちます。