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

Copy
1<?php
2
3// Composerのオートローダーを読み込みます。
4// プロジェクトでComposerを使用している場合、これにより必要なクラスが自動的にロードされます。
5// このファイルを直接実行する前に `composer install` を実行し、`vendor/autoload.php` が
6// 存在することを確認してください。
7require_once __DIR__ . '/vendor/autoload.php';
8
9namespace App\DomExamples;
10
11use Dom\Document;
12use Dom\DocumentFragment;
13use Dom\Node;
14
15/**
16 * Dom\DocumentFragment::compareDocumentPosition メソッドの使用例を示すクラス。
17 *
18 * このクラスは、Dom\DocumentFragment と他のDom\Node間の位置関係を比較する方法を示します。
19 * システムエンジニアを目指す初心者向けに、Composerによるオートロード、
20 * PHPDocコメント、PHPの推奨コーディングスタイルに従っています。
21 */
22class DomFragmentPositionComparer
23{
24    /**
25     * 2つのDOMノード間の位置関係を比較し、結果を分かりやすく出力します。
26     *
27     * @param Node $nodeA 比較する最初のDOMノード（Dom\DocumentFragmentの場合が多い）。
28     * @param Node $nodeB 比較する2番目のDOMノード。
29     * @return void
30     */
31    public function compareAndExplain(Node $nodeA, Node $nodeB): void
32    {
33        echo "--- 比較中のノード --- \n";
34        echo "ノードA: " . ($nodeA->nodeName ?? '不明なノード') . " (タイプ: " . get_class($nodeA) . ")\n";
35        echo "ノードB: " . ($nodeB->nodeName ?? '不明なノード') . " (タイプ: " . get_class($nodeB) . ")\n";
36
37        // Dom\DocumentFragment オブジェクト（$nodeA）に対して、
38        // 別のDom\Node（$nodeB）との位置関係を比較します。
39        // 戻り値はビットマスク（複数の状態を同時に表す整数値）です。
40        $position = $nodeA->compareDocumentPosition($nodeB);
41
42        echo "比較結果 (整数値): " . $position . "\n";
43        echo "結果の解釈:\n";
44
45        // 各定数とビットAND演算子 (&) を用いて、特定の位置関係をチェックします。
46        // PHPのDOM拡張で定義されている定数を使用します。
47        if ($position === 0) {
48            echo "  - 同じノード: ノードAとノードBは同じノードです。\n";
49        }
50        if ($position & Node::DOCUMENT_POSITION_DISCONNECTED) {
51            echo "  - DOMツリーから切り離されている: ノードAとノードBは同じドキュメントやフラグメントに属していません。\n";
52        }
53        if ($position & Node::DOCUMENT_POSITION_PRECEDING) {
54            echo "  - 前にある: ノードBがノードAよりもDOMツリー上で物理的に前にあります。\n";
55        }
56        if ($position & Node::DOCUMENT_POSITION_FOLLOWING) {
57            echo "  - 後にある: ノードBがノードAよりもDOMツリー上で物理的に後にあります。\n";
58        }
59        if ($position & Node::DOCUMENT_POSITION_CONTAINS) {
60            echo "  - 含む: ノードAがノードBを含んでいます（ノードBはノードAの子孫です）。\n";
61        }
62        if ($position & Node::DOCUMENT_POSITION_CONTAINED_BY) {
63            echo "  - 含まれる: ノードAがノードBに含まれています（ノードAはノードBの子孫です）。\n";
64        }
65        if ($position & Node::DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) {
66            echo "  - 実装固有: 比較に実装固有の状態が含まれます。通常、深く考慮する必要はありません。\n";
67        }
68
69        echo "\n";
70    }
71
72    /**
73     * Dom\DocumentFragment::compareDocumentPosition の具体的な使用例を実行します。
74     *
75     * このメソッドは、さまざまなシナリオで比較を行い、Dom\DocumentFragmentがどのように
76     * 他のDOMノードと比較されるかを示します。
77     *
78     * @return void
79     */
80    public function runExamples(): void
81    {
82        // 1. 基本となるDom\Documentを作成し、要素をロードします。
83        $document = new Document('1.0', 'utf-8');
84        // HTML文字列をロードします。これにより、ドキュメント内にDOMツリーが構築されます。
85        $document->loadHTML('<div id="root"><p id="p1">Hello</p><span id="s1">World</span></div>');
86
87        // ドキュメントから既存の要素を取得します。
88        $p1 = $document->getElementById('p1');
89        $s1 = $document->getElementById('s1');
90        $root = $document->getElementById('root');
91
92        // 2. Dom\DocumentFragmentを作成します。
93        // DocumentFragmentは、一時的にノードを保持するための軽量なコンテナで、
94        // まだメインのDOMツリーの一部ではありません。
95        $fragment = new DocumentFragment();
96        $fragmentElement = $document->createElement('li'); // ドキュメントによって要素を作成
97        $fragmentElement->textContent = 'Fragment Item';
98        $fragment->append($fragmentElement); // 要素をフラグメントに追加
99
100        echo "--- シナリオ1: ドキュメント内の要素同士の比較 ---\n";
101        // ドキュメント内のP1要素とS1要素を比較します。
102        // P1はS1よりも前にあるため、S1はP1の後に続きます (DOCUMENT_POSITION_FOLLOWING)。
103        $this->compareAndExplain($p1, $s1);
104
105        echo "--- シナリオ2: 親子要素の比較 ---\n";
106        // ルート要素がP1要素を含んでいるか比較します。
107        // ルートはP1を含んでいるため (DOCUMENT_POSITION_CONTAINS) となります。
108        $this->compareAndExplain($root, $p1);
109
110        echo "--- シナリオ3: Dom\DocumentFragmentとドキュメント内の要素の比較 ---\n";
111        // ドキュメントフラグメントは、まだメインのドキュメントツリーにアタッチされていないため、
112        // ドキュメント内の任意の要素と比較すると 'DISCONNECTED' (切り離されている) となります。
113        $this->compareAndExplain($fragment, $p1);
114
115        echo "--- シナリオ4: Dom\DocumentFragment内の要素とドキュメント内の要素の比較 ---\n";
116        // フラグメント内の要素も、それが属するフラグメントがドキュメントにアタッチされていない限り、
117        // ドキュメント内の要素とは 'DISCONNECTED' となります。
118        $this->compareAndExplain($fragmentElement, $p1);
119
120        echo "--- シナリオ5: 同じノードの比較 ---\n";
121        // 同じノードを比較すると、結果は0になります。
122        $this->compareAndExplain($p1, $p1);
123    }
124}
125
126// DomFragmentPositionComparer クラスのインスタンスを作成し、
127// 定義された比較例を実行します。
128$comparer = new DomFragmentPositionComparer();
129$comparer->runExamples();

Dom\DocumentFragment::compareDocumentPositionメソッドは、現在のDom\DocumentFragmentオブジェクトと、引数で渡された別のDom\Nodeオブジェクトの相対的な位置関係を比較するために使用されます。引数$otherには比較対象となる任意のDOMノードを指定します。

このメソッドは整数値を返しますが、これは複数の状態を同時に表すビットマスクです。戻り値の整数値は、Node::DOCUMENT_POSITION_DISCONNECTED（DOMツリーから切り離されている）、Node::DOCUMENT_POSITION_PRECEDING（比較対象が現在のノードより前にある）、Node::DOCUMENT_POSITION_FOLLOWING（比較対象が現在のノードより後にある）、Node::DOCUMENT_POSITION_CONTAINS（現在のノードが比較対象を含んでいる）、Node::DOCUMENT_POSITION_CONTAINED_BY（現在のノードが比較対象に含まれている）などの定数とビットAND演算子&を使って、個々の位置関係を判断できます。もし戻り値が0であれば、両方のノードが同じノードであることを意味します。

提供されたサンプルコードでは、DocumentFragmentがメインのDOMツリーにアタッチされていない状態では、他のノードと比較すると「切り離されている」という結果が返されることが示されています。また、ドキュメント内の親ノードと子ノードの比較や、同じノード同士の比較など、様々なシナリオでの挙動が具体的な出力例とともに解説されており、このメソッドが複雑なDOM構造においてノード間の正確な位置関係を把握するのに役立つことが分かります。

Copy
1<?php
2
3/**
4 * Dom\DocumentFragment::compareDocumentPosition メソッドの使用例を示します。
5 *
6 * この関数は、Dom\DocumentFragment 内のノード、DocumentFragment 自体、
7 * およびツリーに接続されていないノード間の位置関係を比較する方法を示します。
8 * 比較結果はビットマスクとして返され、ノード間の相対的な位置関係を表現します。
9 *
10 * phpdocumentor オプションの意図を汲み、phpdoc形式のコメントを追加しています。
11 *
12 * @return void
13 */
14function demonstrateDomDocumentFragmentComparison(): void
15{
16    // 1. 新しいDOMドキュメントを作成します。このドキュメントがノードの所有者となります。
17    $dom = new Dom\Document();
18    // HTMLをロードして、基本的なDOMツリーが存在する状態にします（今回の比較には直接影響しませんが、一般的な使用例として）。
19    $dom->loadHTML('<!DOCTYPE html><html><body></body></html>');
20
21    // 2. 新しいDom\DocumentFragmentを作成します。これは一時的に複数のノードを保持できます。
22    $fragment = new Dom\DocumentFragment();
23
24    // 3. DocumentFragmentにノードを追加します。
25    // これらのノードはまだ主ドキュメントのDOMツリーには接続されていません。
26    $elementInsideFragment = $dom->createElement('span', 'フラグメント内の要素。');
27    $textNodeInsideFragment = $dom->createTextNode('フラグメント内のテキスト。');
28    $fragment->append($elementInsideFragment);
29    $fragment->append($textNodeInsideFragment);
30
31    // 4. 文書ツリーにまだ接続されていない別の要素を作成します。
32    // このノードはどのDocumentFragmentにも属していません。
33    $disconnectedElement = $dom->createElement('div', '未接続の要素。');
34
35    // 比較結果（ビットマスク）を人間が読める形式に変換するためのヘルパー関数
36    $getPositionDescription = function (int $position): string {
37        $descriptions = [];
38        if ($position === 0) {
39            return 'SAME_NODE (同じノード)'; // 同じノードと比較した場合に返される
40        }
41        if ($position & Dom\Node::DOCUMENT_POSITION_DISCONNECTED) {
42            $descriptions[] = 'DISCONNECTED (分離)';
43        }
44        if ($position & Dom\Node::DOCUMENT_POSITION_PRECEDING) {
45            $descriptions[] = 'PRECEDING (前にある)';
46        }
47        if ($position & Dom\Node::DOCUMENT_POSITION_FOLLOWING) {
48            $descriptions[] = 'FOLLOWING (後にある)';
49        }
50        if ($position & Dom\Node::DOCUMENT_POSITION_CONTAINS) {
51            $descriptions[] = 'CONTAINS (含まれる)'; // 比較元が比較対象を含む
52        }
53        if ($position & Dom\Node::DOCUMENT_POSITION_CONTAINED_BY) {
54            $descriptions[] = 'CONTAINED_BY (含まれている)'; // 比較元が比較対象に含まれる
55        }
56        if ($position & Dom\Node::DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) {
57            $descriptions[] = 'IMPLEMENTATION_SPECIFIC (実装固有)';
58        }
59        return empty($descriptions) ? 'UNKNOWN (不明)' : implode(' | ', $descriptions);
60    };
61
62    echo "--- Dom\\DocumentFragment::compareDocumentPosition の使用例 ---\n\n";
63    echo "注: \$this->compareDocumentPosition(\$other) は、\$other が \$this に対してどの位置にあるかを返します。\n\n";
64
65    // シナリオ 1: フラグメント内の要素 ($elementInsideFragment) とフラグメント ($fragment) 自体を比較
66    // \$elementInsideFragment から見て、\$fragment は自身を「含んでいる」祖先ノードであり、「前」に位置します。
67    $pos1 = $elementInsideFragment->compareDocumentPosition($fragment);
68    echo "1. フラグメント内の要素 ('" . $elementInsideFragment->nodeName . "') とフラグメント ('" . $fragment->nodeName . "') の比較:\n";
69    echo "   結果 (int): $pos1\n";
70    echo "   意味: " . $getPositionDescription($pos1) . "\n\n";
71    // 期待値: CONTAINED_BY (0x10) | PRECEDING (0x02) => 18
72
73    // シナリオ 2: フラグメント ($fragment) とフラグメント内の要素 ($elementInsideFragment) を比較
74    // \$fragment から見て、\$elementInsideFragment は自身に「含まれる」子孫ノードであり、「後」に位置します。
75    $pos2 = $fragment->compareDocumentPosition($elementInsideFragment);
76    echo "2. フラグメント ('" . $fragment->nodeName . "') とフラグメント内の要素 ('" . $elementInsideFragment->nodeName . "') の比較:\n";
77    echo "   結果 (int): $pos2\n";
78    echo "   意味: " . $getPositionDescription($pos2) . "\n\n";
79    // 期待値: CONTAINS (0x08) | FOLLOWING (0x04) => 12
80
81    // シナリオ 3: フラグメント ($fragment) と文書ツリーに接続されていない要素 ($disconnectedElement) を比較
82    // どちらのノードもDOMツリーに接続されておらず、互いに親子関係も兄弟関係もないため、「分離」関係です。
83    $pos3 = $fragment->compareDocumentPosition($disconnectedElement);
84    echo "3. フラグメント ('" . $fragment->nodeName . "') と未接続の要素 ('" . $disconnectedElement->nodeName . "') の比較:\n";
85    echo "   結果 (int): $pos3\n";
86    echo "   意味: " . $getPositionDescription($pos3) . "\n\n";
87    // 期待値: DISCONNECTED (0x01) => 1
88
89    // シナリオ 4: フラグメント内のテキストノードとフラグメント内の別の要素を比較
90    // 同じフラグメント内だが、互いに親子関係ではない兄弟ノードです。
91    // appendの順序により $elementInsideFragment が $textNodeInsideFragment の「前」にあります。
92    $pos4 = $textNodeInsideFragment->compareDocumentPosition($elementInsideFragment);
93    echo "4. フラグメント内のテキストノード ('" . $textNodeInsideFragment->nodeName . "') と要素 ('" . $elementInsideFragment->nodeName . "') の比較:\n";
94    echo "   結果 (int): $pos4\n";
95    echo "   意味: " . $getPositionDescription($pos4) . "\n\n";
96    // 期待値: PRECEDING (0x02) => 2
97
98    // シナリオ 5: フラグメント内の要素とフラグメント内のテキストノードを比較
99    // $elementInsideFragment から見て、$textNodeInsideFragment は「後」にあります。
100    $pos5 = $elementInsideFragment->compareDocumentPosition($textNodeInsideFragment);
101    echo "5. フラグメント内の要素 ('" . $elementInsideFragment->nodeName . "') とテキストノード ('" . $textNodeInsideFragment->nodeName . "') の比較:\n";
102    echo "   結果 (int): $pos5\n";
103    echo "   意味: " . $getPositionDescription($pos5) . "\n\n";
104    // 期待値: FOLLOWING (0x04) => 4
105}
106
107// サンプル関数の実行
108demonstrateDomDocumentFragmentComparison();
109
110?>

PHPのDom\DocumentFragment::compareDocumentPositionメソッドは、ウェブページの要素間の関係を把握し、プログラムで操作する際に利用されます。このメソッドは、比較元のノードが引数で指定された別のノードに対して、DOMツリー上のどの位置にあるかを判別します。Dom\DocumentFragmentは一時的にノードを保持するコンテナであり、まだ実際のドキュメントツリーに接続されていないノード間の位置関係も比較できる点が特徴です。

引数 $other には、比較対象となる別の Dom\Node オブジェクトを指定します。メソッドは整数値を返しますが、これは複数の情報を組み合わせたビットマスクです。例えば、一方のノードがもう一方を「含んでいる」か、「含まれている」か、あるいは「前にある」か、「後にある」か、またはDOMツリー上で「分離」しているかといった、ノード間の相対的な位置関係がこの戻り値によって示されます。具体的には、親子関係、兄弟関係、または完全に独立した関係など、さまざまな状況をこの単一の整数値で判別できます。この機能は、ウェブページの構造を動的に解析し、その位置に基づいて特定の処理を行う場合に有用です。