【PHP8.x】Dom\HTMLElement::DOCUMENT_POSITION_FOLLOWING定数の使い方

DOCUMENT_POSITION_FOLLOWING定数の使い方について、初心者にもわかりやすく解説します。

作成日: 2025年09月11日更新日: 2025年11月21日

基本的な使い方

DOCUMENT_POSITION_FOLLOWING定数は、PHPのDOM拡張機能において、DOMツリー内のノード（要素やテキストノードなど）間の相対的な位置関係を表すために使用される定数です。特に、Dom\HTMLElementクラスを含むDOMノード同士を比較する際に利用されます。

この定数は、DOMNodeクラスが提供するcompareDocumentPositionメソッドの戻り値として、ビットマスクの一部として返されることがあります。compareDocumentPositionメソッドは、あるノードが別のノードに対してDOMツリー内でどのような位置にあるか（先行するか、後続するか、親か子か、あるいは同じノードかなど）を数値で示します。

その戻り値にDOCUMENT_POSITION_FOLLOWING定数の値が含まれている場合、それは比較対象のノードが、基準となるノードに対して、DOMツリーの文書順序において「後方」に位置していることを意味します。例えば、HTML文書の構造を考えた際に、基準となる要素よりも後に記述されている要素であれば、この定数がセットされます。

これにより、開発者はスクリプト内で、プログラム的にDOMノードの相対的な位置を判断し、それに基づいて処理を分岐させたり、特定の順序でノードを操作したりすることが可能になります。この定数は、複雑なDOM操作において、ノード間の空間的・論理的関係を把握するための重要なツールとなります。

構文(syntax)


1<?php
2echo Dom\HTMLElement::DOCUMENT_POSITION_FOLLOWING;
3?>

引数(parameters)

引数なし

引数はありません

戻り値(return)

int

DOCUMENT_POSITION_FOLLOWING は、DOMツリーにおいて、あるノードが別のノードの後に続く位置関係を示す整数定数です。

サンプルコード

DOMノード位置関係比較：DOCUMENT_POSITION_FOLLOWINGとPRECEDING


1<?php
2
3/**
4 * DOMノードの位置関係を比較する関数。
5 *
6 * この関数は、Dom\Node::compareDocumentPosition メソッドを使用して、
7 * 2つのDOMノード間の相対的な位置関係を判断する方法を示します。
8 * 特に、DOCUMENT_POSITION_FOLLOWING と DOCUMENT_POSITION_PRECEDING 定数の使用例を扱います。
9 * システムエンジニアを目指す初心者向けに、DOMツリー内でのノードの順序を理解するのに役立ちます。
10 */
11function compareDomNodePositions(): void
12{
13    // 1. 新しいDOMドキュメントを作成し、簡単なHTML構造をロード
14    $dom = new Dom\Document();
15    // 比較のために親子関係と兄弟関係を持つノードを含めます。
16    // id を付与して、ノードを簡単に取得できるようにします。
17    $dom->loadHTML('
18        <!DOCTYPE html>
19        <html>
20        <body>
21            <div id="parent_container">
22                <p id="first_element">最初の要素</p>
23                <span id="second_element">二番目の要素</span>
24            </div>
25        </body>
26        </html>
27    ');
28
29    // 2. 比較対象となるDOMノードを取得
30    // getElementById は Dom\Element オブジェクトを返します。Dom\Element は Dom\Node を継承しています。
31    $parentNode = $dom->getElementById('parent_container');
32    $firstElement = $dom->getElementById('first_element');
33    $secondElement = $dom->getElementById('second_element');
34
35    // 必要なノードが全て取得できたかを確認
36    if (!$parentNode || !$firstElement || !$secondElement) {
37        echo "エラー: 必要なDOMノードが見つかりませんでした。HTML構造を確認してください。\n";
38        return;
39    }
40
41    echo "--- DOM ノード位置関係の比較 ---\n\n";
42
43    // 3. ノード間の位置関係を比較し、結果を出力
44
45    // 例1: 兄弟ノードの比較 (最初の要素 と 二番目の要素)
46    // $firstElement から見て $secondElement がどこにあるか
47    echo "--- 兄弟ノードの比較: \$firstElement と \$secondElement ---\n";
48    $result1 = $firstElement->compareDocumentPosition($secondElement);
49
50    // DOCUMENT_POSITION_FOLLOWING は、比較対象のノードが参照ノードの後に位置することを示します。
51    if ($result1 & Dom\Node::DOCUMENT_POSITION_FOLLOWING) {
52        echo "\t\$secondElement は \$firstElement の後に位置します。\n";
53    } else {
54        echo "\t\$secondElement は \$firstElement の後に位置しません。\n";
55    }
56    echo "\t(Dom\\Node::DOCUMENT_POSITION_FOLLOWING の値: " . Dom\Node::DOCUMENT_POSITION_FOLLOWING . ")\n\n";
57
58
59    // 例2: 兄弟ノードの比較 (二番目の要素 と 最初の要素) - 逆方向
60    // $secondElement から見て $firstElement がどこにあるか
61    echo "--- 兄弟ノードの比較 (逆方向): \$secondElement と \$firstElement ---\n";
62    $result2 = $secondElement->compareDocumentPosition($firstElement);
63
64    // DOCUMENT_POSITION_PRECEDING は、比較対象のノードが参照ノードの前に位置することを示します。
65    if ($result2 & Dom\Node::DOCUMENT_POSITION_PRECEDING) {
66        echo "\t\$firstElement は \$secondElement の前に位置します。\n";
67    } else {
68        echo "\t\$firstElement は \$secondElement の前に位置しません。\n";
69    }
70    echo "\t(Dom\\Node::DOCUMENT_POSITION_PRECEDING の値: " . Dom\Node::DOCUMENT_POSITION_PRECEDING . ")\n\n";
71
72
73    // 例3: 親子ノードの比較 (親要素 と 最初の子要素)
74    // $parentNode から見て $firstElement がどこにあるか
75    echo "--- 親子ノードの比較: \$parentNode と \$firstElement ---\n";
76    $result3 = $parentNode->compareDocumentPosition($firstElement);
77
78    // DOCUMENT_POSITION_CONTAINED_BY は、比較対象のノードが参照ノードに含まれることを示します。
79    // 含まれるノードは通常、親ノードの後にDOMツリー内で現れるため、DOCUMENT_POSITION_FOLLOWING も同時に適用されます。
80    if (($result3 & Dom\Node::DOCUMENT_POSITION_CONTAINED_BY) && ($result3 & Dom\Node::DOCUMENT_POSITION_FOLLOWING)) {
81        echo "\t\$firstElement は \$parentNode に含まれており、\$parentNode の後に位置します。\n";
82    } elseif ($result3 & Dom\Node::DOCUMENT_POSITION_FOLLOWING) {
83        echo "\t\$firstElement は \$parentNode の後に位置します。\n";
84    }
85    echo "\n";
86
87    // 例4: 親子ノードの比較 (子要素 と 親要素) - 逆方向
88    // $firstElement から見て $parentNode がどこにあるか
89    echo "--- 親子ノードの比較 (逆方向): \$firstElement と \$parentNode ---\n";
90    $result4 = $firstElement->compareDocumentPosition($parentNode);
91
92    // DOCUMENT_POSITION_CONTAINS は、参照ノードが比較対象のノードを含むことを示します。
93    // 参照ノードが比較対象のノードを含む場合、参照ノードはDOMツリー内で前に現れるため、DOCUMENT_POSITION_PRECEDING も同時に適用されます。
94    if (($result4 & Dom\Node::DOCUMENT_POSITION_CONTAINS) && ($result4 & Dom\Node::DOCUMENT_POSITION_PRECEDING)) {
95        echo "\t\$parentNode は \$firstElement を含んでおり、\$firstElement の前に位置します。\n";
96    } elseif ($result4 & Dom\Node::DOCUMENT_POSITION_PRECEDING) {
97        echo "\t\$parentNode は \$firstElement の前に位置します。\n";
98    }
99    echo "\n";
100
101
102    // 例5: 接続されていないノードの比較
103    echo "--- 接続されていないノードの比較: \$parentNode と 新しいノード ---\n";
104    $disconnectedNode = $dom->createElement('div', '完全に別のノード');
105    $result5 = $parentNode->compareDocumentPosition($disconnectedNode);
106
107    // DOCUMENT_POSITION_DISCONNECTED は、両方のノードが同じDOMツリーに接続されていないことを示します。
108    if ($result5 & Dom\Node::DOCUMENT_POSITION_DISCONNECTED) {
109        echo "\t新しいノードは \$parentNode と同じDOMツリーに接続されていません。\n";
110    }
111    echo "\t(Dom\\Node::DOCUMENT_POSITION_DISCONNECTED の値: " . Dom\Node::DOCUMENT_POSITION_DISCONNECTED . ")\n\n";
112}
113
114// 関数を実行して、DOMノードの位置関係を確認します。
115compareDomNodePositions();
116

このサンプルコードは、PHPでウェブページの構造を表すDOM（Document Object Model）ノード間の相対的な位置関係を比較する方法を示しています。具体的には、Dom\NodeクラスのcompareDocumentPositionメソッドと、その戻り値で使われる様々な位置関係を示す定数について解説します。

compareDocumentPositionメソッドは、現在のノードから見て、引数で渡された別のノードがDOMツリー内のどこに位置するかを判定します。引数には比較したいDom\Nodeオブジェクトを指定し、戻り値は整数値で、複数の位置関係を示す情報（ビットマスク）が組み合わされています。

主要な定数として、Dom\Node::DOCUMENT_POSITION_FOLLOWINGは、比較対象のノードが現在のノードの後に位置することを示します。例えば、HTMLで先に書かれた要素と後に書かれた要素の関係を判断する際に使用されます。逆に、Dom\Node::DOCUMENT_POSITION_PRECEDINGは、比較対象のノードが現在のノードの前に位置することを示します。他にも、ノードが別のノードに含まれているかを示すDOCUMENT_POSITION_CONTAINED_BYや、逆に含んでいるかを示すDOCUMENT_POSITION_CONTAINS、全く異なるDOMツリーに属しているかを示すDOCUMENT_POSITION_DISCONNECTEDといった定数があります。

サンプルコードでは、まずHTMLを読み込み、複数のDOMノードを取得しています。次に、兄弟ノード、親子ノード、さらにはDOMツリーに接続されていないノード同士を比較し、compareDocumentPositionメソッドの戻り値と、各定数をビット演算子&で組み合わせて、期待される位置関係かどうかを判定し、その結果を出力しています。これにより、DOMツリーにおけるノードの順序や包含関係を正確に把握する方法を学ぶことができます。

このサンプルコードで Dom\Node::compareDocumentPosition メソッドを使う際は、戻り値が複数の位置関係を示すビットフラグの整数である点に注意が必要です。特定の定数を確認するには、== (等価比較) ではなく、& (ビットAND演算子) を用いて判定する必要があります。これにより、複数の状態が同時に真となる場合でも正しく認識できます。

DOCUMENT_POSITION_FOLLOWING は比較対象ノードが参照ノードの後に位置することを、DOCUMENT_POSITION_PRECEDING は前に位置することを示します。これらの判断は「基準となるノードから見て」行われるため、どちらのノードが基準か意識してください。

また、DOCUMENT_POSITION_CONTAINS や DOCUMENT_POSITION_CONTAINED_BY といった親子関係のフラグも、FOLLOWING や PRECEDING と組み合わさって返される場合があります。DOMツリーの構造を理解することで、これらの複合的な結果も正確に読み解くことができます。DOMノードを取得する際は、getElementById の結果が null でないか必ず確認し、エラーを防ぐようにしてください。

PHP 8 DOM 要素位置比較: DOCUMENT_POSITION_FOLLOWING


1<?php
2
3/**
4 * 2つのDOM要素の位置関係を比較し、一方の要素がもう一方の要素の後続にあるかを判定します。
5 *
6 * この関数は、システムエンジニアを目指す初心者がDOM要素の比較方法と
7 * Dom\HTMLElement::DOCUMENT_POSITION_FOLLOWING 定数の使用方法を理解するのに役立ちます。
8 * 特に、指定された $secondNode が $firstNode の DOM ツリー上で「後続 (post)」に位置するかどうかを評価します。
9 *
10 * @param Dom\HTMLElement $firstNode 比較対象となる最初のDOM要素。
11 * @param Dom\HTMLElement $secondNode 比較対象となる2番目のDOM要素。
12 *                                  この「param」要素が $firstNode の「post」に位置するかどうかを判定します。
13 * @return bool $secondNode が $firstNode の後続に位置する場合は true、そうでない場合は false。
14 */
15function compareNodePositions(Dom\HTMLElement $firstNode, Dom\HTMLElement $secondNode): bool
16{
17    // DOMNode::compareDocumentPosition メソッドは、2つのノード間の位置関係を示すビットマスクを返します。
18    // PHP 8ではDOMElementがDom\HTMLElementインターフェースを実装しているため、
19    // Dom\HTMLElement 型の引数に対してこのメソッドを直接呼び出すことができます。
20    $position = $firstNode->compareDocumentPosition($secondNode);
21
22    // Dom\HTMLElement::DOCUMENT_POSITION_FOLLOWING 定数は、
23    // 参照ノード ($firstNode) が比較ノード ($secondNode) の前にあり、
24    // $secondNode が $firstNode の「後続」に続くことを示すビットマスクです。
25    // ビットAND演算子 (&) を使用して、compareDocumentPosition の戻り値に
26    // DOCUMENT_POSITION_FOLLOWING が含まれているか（つまり、ビットが立っているか）を確認します。
27    return (bool)($position & Dom\HTMLElement::DOCUMENT_POSITION_FOLLOWING);
28}
29
30// === サンプルコードの実行部分 ===
31
32// 1. 簡単なHTMLドキュメントを作成し、DOMオブジェクトに読み込みます。
33$htmlString = <<<HTML
34<!DOCTYPE html>
35<html>
36<head><title>DOM Position Test</title></head>
37<body>
38    <div id="container">
39        <p id="first">これは最初の段落です。</p>
40        <span id="middle">これは途中のスパンです。</span>
41        <a href="#" id="last">これは最後のリンクです。</a>
42    </div>
43</body>
44</html>
45HTML;
46
47$dom = new DOMDocument();
48// HTMLを読み込む際にエラーを抑制し、標準的なHTML5の構造を維持するために追加タグを抑制します。
49@$dom->loadHTML($htmlString, LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD);
50
51// DOMXPath を使用して、HTMLドキュメントから特定の要素を簡単に取得します。
52$xpath = new DOMXPath($dom);
53
54// 各要素をIDで取得します。DOMXPath::query は DOMNodeList を返すため、item(0) で最初の要素を取得します。
55// PHP 8ではDOMElementがDom\HTMLElementを実装しているため、これらの要素はDom\HTMLElementとして扱えます。
56$firstParagraph = $xpath->query('//p[@id="first"]')->item(0);
57$middleSpan = $xpath->query('//span[@id="middle"]')->item(0);
58$lastLink = $xpath->query('//a[@id="last"]')->item(0);
59
60// 取得した要素がすべて有効であるか確認します。
61if ($firstParagraph instanceof Dom\HTMLElement &&
62    $middleSpan instanceof Dom\HTMLElement &&
63    $lastLink instanceof Dom\HTMLElement) {
64
65    echo "--- DOM要素の位置関係の比較 ---" . PHP_EOL . PHP_EOL;
66
67    // テストケース 1: $lastLink は $firstParagraph の後続に位置するか？ (期待値: true)
68    $isLastFollowingFirst = compareNodePositions($firstParagraph, $lastLink);
69    echo "IDが 'last' の要素は IDが 'first' の要素の後続にありますか？ " . ($isLastFollowingFirst ? "はい" : "いいえ") . PHP_EOL;
70
71    // テストケース 2: $firstParagraph は $lastLink の後続に位置するか？ (期待値: false)
72    $isFirstFollowingLast = compareNodePositions($lastLink, $firstParagraph);
73    echo "IDが 'first' の要素は IDが 'last' の要素の後続にありますか？ " . ($isFirstFollowingLast ? "はい" : "いいえ") . PHP_EOL;
74
75    // テストケース 3: $middleSpan は $firstParagraph の後続に位置するか？ (期待値: true)
76    $isMiddleFollowingFirst = compareNodePositions($firstParagraph, $middleSpan);
77    echo "IDが 'middle' の要素は IDが 'first' の要素の後続にありますか？ " . ($isMiddleFollowingFirst ? "はい" : "いいえ") . PHP_EOL;
78
79    // テストケース 4: $firstParagraph は $middleSpan の後続に位置するか？ (期待値: false)
80    $isFirstFollowingMiddle = compareNodePositions($middleSpan, $firstParagraph);
81    echo "IDが 'first' の要素は IDが 'middle' の要素の後続にありますか？ " . ($isFirstFollowingMiddle ? "はい" : "いいえ") . PHP_EOL;
82
83} else {
84    echo "必要なDOM要素が見つかりませんでした。HTML構造やIDを確認してください。" . PHP_EOL;
85}

このPHPコードは、ウェブページの構造を表すDOM（Document Object Model）要素間の位置関係を比較する方法を示しています。特に、あるDOM要素が別のDOM要素の「後続（次に位置する）」にあるかどうかを判定するcompareNodePositions関数を定義しています。

compareNodePositions関数は、比較対象となる最初のDOM要素である$firstNodeと、その位置を$firstNodeと比較する2番目のDOM要素である$secondNodeの二つのDom\HTMLElement型の引数を受け取ります。この関数は、$secondNodeがDOMツリー上で$firstNodeの後続に位置するかどうかを判断します。内部では、$firstNodeのcompareDocumentPositionメソッドの結果をDom\HTMLElement::DOCUMENT_POSITION_FOLLOWING定数と比較しています。この定数は、要素が後続にあることを示す特定のビットパターンを表しており、ビットAND演算子を使って含まれているかを確認します。関数は、$secondNodeが$firstNodeの後続に位置する場合はtrueを、そうでない場合はfalseをブール値として返します。

サンプルコードの実行部分では、簡単なHTML文字列をDOMオブジェクトとして読み込み、XPathを使用して特定の要素を取得しています。そして、これらの取得した要素をcompareNodePositions関数に渡し、複数のパターンで要素間の後続関係を比較し、その結果をコンソールに出力して具体的な挙動を示しています。

このサンプルコードは、PHP 8以降でDOM要素の位置関係を比較する方法を示しています。Dom\HTMLElement::DOCUMENT_POSITION_FOLLOWING定数は、比較対象の要素が基準要素のDOMツリー上で「後続」に位置するかを判定するために使用します。コード内のpostやparamは、定数の意味や引数の役割を説明するための補足的なキーワードと理解してください。compareDocumentPositionメソッドの戻り値はビットマスクであるため、ビットAND演算子&で定数と比較することで、特定の関係性を正確に判定しています。DOMDocument::loadHTMLのエラー抑制@は、運用時は適切なエラー処理に置き換え、DOMXPath::queryで取得した要素はitem(0)とinstanceofで確実に型を確認することが重要です。