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

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

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

基本的な使い方

DOCUMENT_POSITION_FOLLOWING定数は、DOM (Document Object Model) におけるノード間の関係を表す定数です。具体的には、あるノードが別のノードよりもドキュメントツリー内で後に続く位置にあることを示します。この定数は、DOMNode::compareDocumentPosition メソッドの結果として返される値の一部として使用されます。DOMNode::compareDocumentPosition メソッドは、2つのノード間のドキュメント内の位置関係を比較し、ビットマスク形式で結果を返します。そのビットマスクの中に DOCUMENT_POSITION_FOLLOWING 定数が含まれている場合、比較対象のノードが基準ノードよりも後に存在することを意味します。システムエンジニアを目指す初心者の方にとって、この定数は、DOMを操作する際に、ノード間の相対的な位置を把握し、プログラムで適切に処理するために重要な役割を果たします。例えば、特定のノードの後に新しいノードを挿入する処理や、ドキュメント内のノードの順序に基づいて何らかの処理を行う場合に、この定数を利用して条件分岐を行うことができます。この定数の値は数値として定義されており、他の DOCUMENT_POSITION_* 定数と組み合わせて使用することで、より詳細なノード間の位置関係を判別できます。DOMを扱う上で、ノード間の関係性を理解することは、効率的かつ正確なプログラムを作成するために不可欠です。

構文(syntax)


1Dom\Document::DOCUMENT_POSITION_FOLLOWING

引数(parameters)

引数なし

引数はありません

戻り値(return)

int

DOCUMENT_POSITION_FOLLOWING は、DOMNode の位置関係を示す定数で、ノードが指定されたノードの後に続くことを示します。この定数は整数値 4 を持ちます。

サンプルコード

PHP DOMノード位置関係の比較


1<?php
2
3/**
4 * DOMノード間の位置関係を比較するPHP 8のサンプルコードです。
5 * Dom\Document::DOCUMENT_POSITION_FOLLOWING および DOCUMENT_POSITION_PRECEDING 定数を使用して、
6 * HTMLドキュメント内のノードが別のノードに対して「前方」にあるか「後方」にあるかを示します。
7 */
8function demonstrateDocumentPositionComparison(): void
9{
10    // 新しい Dom\Document オブジェクトを作成します。
11    $dom = new Dom\Document();
12
13    // サンプルとなるHTMLコンテンツをロードします。
14    // 日本語の文字化けを防ぐため、メタタグでUTF-8を指定します。
15    $dom->loadHTML('
16        <!DOCTYPE html>
17        <html>
18        <head>
19            <meta charset="UTF-8">
20        </head>
21        <body>
22            <div id="container">
23                <p id="firstP">これは最初の段落です。</p>
24                <span id="targetSpan">これはターゲットのSPANです。</span>
25                <p id="secondP">これは2番目の段落です。</p>
26            </div>
27            <div id="anotherDiv">
28                <p id="outsideP">これは別のDIVの段落です。</p>
29            </div>
30        </body>
31        </html>
32    ');
33
34    // 比較対象となる特定のノードをIDで取得します。
35    $firstP = $dom->getElementById('firstP');
36    $targetSpan = $dom->getElementById('targetSpan');
37    $secondP = $dom->getElementById('secondP');
38    $outsideP = $dom->getElementById('outsideP');
39
40    echo "=== DOMノード間の位置比較のデモンストレーション ===\n\n";
41
42    // 取得したノードが存在するか確認します。
43    if ($firstP && $targetSpan && $secondP && $outsideP) {
44
45        // 例1: targetSpan と firstP の比較
46        // targetSpan はHTML構造上で firstP の後に位置しています。
47        // したがって、比較結果には DOCUMENT_POSITION_FOLLOWING が含まれます。
48        $position1 = $targetSpan->compareDocumentPosition($firstP);
49        echo "1. 'targetSpan' と 'firstP' の比較:\n";
50        echo "   - 'targetSpan' は 'firstP' の ";
51        if ($position1 & Dom\Document::DOCUMENT_POSITION_FOLLOWING) {
52            echo "後方に位置しています (DOCUMENT_POSITION_FOLLOWING)。\n";
53        } elseif ($position1 & Dom\Document::DOCUMENT_POSITION_PRECEDING) {
54            echo "前方に位置しています (DOCUMENT_POSITION_PRECEDING)。\n";
55        } else {
56            echo "特定の位置関係にはありません。\n";
57        }
58        echo "   (戻り値のビットマスク: 0x" . dechex($position1) . ")\n\n";
59
60
61        // 例2: firstP と targetSpan の比較
62        // firstP はHTML構造上で targetSpan の前に位置しています。
63        // したがって、比較結果には DOCUMENT_POSITION_PRECEDING が含まれます。
64        $position2 = $firstP->compareDocumentPosition($targetSpan);
65        echo "2. 'firstP' と 'targetSpan' の比較:\n";
66        echo "   - 'firstP' は 'targetSpan' の ";
67        if ($position2 & Dom\Document::DOCUMENT_POSITION_PRECEDING) {
68            echo "前方に位置しています (DOCUMENT_POSITION_PRECEDING)。\n";
69        } elseif ($position2 & Dom\Document::DOCUMENT_POSITION_FOLLOWING) {
70            echo "後方に位置しています (DOCUMENT_POSITION_FOLLOWING)。\n";
71        } else {
72            echo "特定の位置関係にはありません。\n";
73        }
74        echo "   (戻り値のビットマスク: 0x" . dechex($position2) . ")\n\n";
75
76
77        // 例3: targetSpan と secondP の比較
78        // targetSpan はHTML構造上で secondP の前に位置しています。
79        // したがって、比較結果には DOCUMENT_POSITION_PRECEDING が含まれます。
80        $position3 = $targetSpan->compareDocumentPosition($secondP);
81        echo "3. 'targetSpan' と 'secondP' の比較:\n";
82        echo "   - 'targetSpan' は 'secondP' の ";
83        if ($position3 & Dom\Document::DOCUMENT_POSITION_PRECEDING) {
84            echo "前方に位置しています (DOCUMENT_POSITION_PRECEDING)。\n";
85        } elseif ($position3 & Dom\Document::DOCUMENT_POSITION_FOLLOWING) {
86            echo "後方に位置しています (DOCUMENT_POSITION_FOLLOWING)。\n";
87        } else {
88            echo "特定の位置関係にはありません。\n";
89        }
90        echo "   (戻り値のビットマスク: 0x" . dechex($position3) . ")\n\n";
91
92
93        // 例4: targetSpan と outsideP の比較
94        // これらは異なる親要素の下にあるため、直接的な兄弟関係や包含関係にはありません。
95        // 同じドキュメント内にはありますが、DOMツリーの異なるサブツリーに属しています。
96        // この場合、DOCUMENT_POSITION_DISCONNECTED が含まれます。
97        $position4 = $targetSpan->compareDocumentPosition($outsideP);
98        echo "4. 'targetSpan' と 'outsideP' の比較:\n";
99        echo "   - 'targetSpan' と 'outsideP' は ";
100        if ($position4 & Dom\Document::DOCUMENT_POSITION_DISCONNECTED) {
101            echo "切断された関係にあります (DOCUMENT_POSITION_DISCONNECTED)。\n";
102            echo "     (異なるサブツリーに属するため、このフラグが立ちます。)\n";
103        }
104        if ($position4 & Dom\Document::DOCUMENT_POSITION_FOLLOWING) {
105            echo "     かつ 'targetSpan' は 'outsideP' の後方に位置しています。\n";
106        } elseif ($position4 & Dom\Document::DOCUMENT_POSITION_PRECEDING) {
107            echo "     かつ 'targetSpan' は 'outsideP' の前方に位置しています。\n";
108        }
109        echo "   (戻り値のビットマスク: 0x" . dechex($position4) . ")\n\n";
110
111    } else {
112        echo "エラー: 指定されたIDを持つノードの一部が見つかりませんでした。HTML構造を確認してください。\n";
113    }
114}
115
116// 関数を実行してデモンストレーションを開始します。
117demonstrateDocumentPositionComparison();

このPHPサンプルコードは、HTMLなどのDOM（Document Object Model）構造における二つの要素（ノード）の相対的な位置関係を調べる方法を示しています。具体的には、Dom\Nodeオブジェクトが持つcompareDocumentPosition()メソッドを利用します。このメソッドは、引数に渡されたノードが、メソッドを呼び出したノードのDOMツリー上のどこに位置するかを、整数値（ビットマスク）で返します。

戻り値に含まれる定数の一つであるDom\Document::DOCUMENT_POSITION_FOLLOWINGは、比較対象のノードが基準ノードの後に続く場合にその位置関係を示します。逆に、Dom\Document::DOCUMENT_POSITION_PRECEDINGは、比較対象のノードが基準ノードの前に存在する場合にその位置関係を示す定数です。

サンプルコードでは、まずHTMLコンテンツをDom\Documentオブジェクトに読み込み、特定のIDを持つ複数のノードを取得します。その後、これらのノード間でcompareDocumentPosition()メソッドを実行し、返されたビットマスクと各定数をビット演算子&で比較することで、ノードの具体的な位置関係を判定し、結果を出力しています。例えば、ターゲットのSPAN要素が最初の段落要素の後に配置されている場合、DOCUMENT_POSITION_FOLLOWINGが検出され、その旨が表示されます。また、異なる親要素を持つノード間ではDOCUMENT_POSITION_DISCONNECTEDも考慮される点も示しています。このメソッドの引数は比較対象のノードで、戻り値はノード間の位置関係を示す整数型のビットマスクです。

Dom\Document::compareDocumentPositionメソッドは、二つのDOMノード間の位置関係を示す整数値（ビットマスク）を返します。この戻り値は、DOCUMENT_POSITION_FOLLOWINGやDOCUMENT_POSITION_PRECEDING、DOCUMENT_POSITION_DISCONNECTEDといった複数の定数を組み合わせたものであるため、それぞれの状態を判定するにはビット論理積（&）演算子を用いる必要があります。サンプルコードのように複数のフラグを組み合わせた結果を正しく解釈してください。HTMLコンテンツを読み込む際には、日本語などのマルチバイト文字が正しく表示されるよう、HTML内に必ず<meta charset="UTF-8">といった適切な文字エンコーディング指定を含めてください。また、DOMノードの取得はgetElementByIdなどのメソッドで行いますが、指定したIDの要素が存在しない場合、戻り値はnullとなりますので、比較処理を行う前にノードが取得できているかどうかの確認を怠らないようにしてください。

PHP: Domノード位置比較をDOCUMENTPOSITIONFOLLOWINGで示す


1<?php
2
3/**
4 * 二つの DOM ノードの位置関係を比較し、その結果を出力する関数です。
5 * Dom\Document::DOCUMENT_POSITION_FOLLOWING 定数の具体的な使用方法を、
6 * システムエンジニアを目指す初心者にも分かりやすく示します。
7 *
8 * `phpdoc` の `@param` タグを用いて、引数の型と説明を明記しています。
9 * `DOCUMENT_POSITION_FOLLOWING` は、基準となるノードの「後」に比較対象ノードが存在する場合に
10 * 戻り値のビットマスクに含まれる定数です。
11 *
12 * @param Dom\Element $node1 比較の基準となる最初のノード。
13 * @param Dom\Element $node2 最初のノードと比較される二番目のノード。
14 * @return void この関数は結果を標準出力に出力するため、明示的な戻り値はありません。
15 */
16function compareAndDescribeDomPosition(Dom\Element $node1, Dom\Element $node2): void
17{
18    echo "--- DOM ノード位置比較のデモンストレーション ---\n";
19    echo "基準ノード: '{$node1->textContent}' (ID: {$node1->getAttribute('id')})\n";
20    echo "比較ノード: '{$node2->textContent}' (ID: {$node2->getAttribute('id')})\n";
21
22    // node1 から見て node2 がどこにあるかを判断します。
23    // compareDocumentPosition メソッドはビットマスクを返します。
24    $position = $node1->compareDocumentPosition($node2);
25
26    echo "compareDocumentPosition の結果 (ビットマスク値): " . $position . "\n";
27
28    // Dom\Document::DOCUMENT_POSITION_FOLLOWING は、基準ノード (node1) の後に
29    // 比較ノード (node2) が続くことを示す定数です。
30    // 結果がビットマスクであるため、ビット論理積 (&) と比較することで定数が含まれているか確認します。
31    if (($position & Dom\Document::DOCUMENT_POSITION_FOLLOWING) === Dom\Document::DOCUMENT_POSITION_FOLLOWING) {
32        echo "-> 結果: 比較ノードは基準ノードの後に続いています (DOCUMENT_POSITION_FOLLOWING)。\n";
33    } elseif (($position & Dom\Document::DOCUMENT_POSITION_PRECEDING) === Dom\Document::DOCUMENT_POSITION_PRECEDING) {
34        echo "-> 結果: 比較ノードは基準ノードの前にあります (DOCUMENT_POSITION_PRECEDING)。\n";
35    } elseif (($position & Dom\Document::DOCUMENT_POSITION_CONTAINS) === Dom\Document::DOCUMENT_POSITION_CONTAINS) {
36        echo "-> 結果: 基準ノードが比較ノードを含んでいます (DOCUMENT_POSITION_CONTAINS)。\n";
37    } elseif (($position & Dom\Document::DOCUMENT_POSITION_CONTAINED_BY) === Dom\Document::DOCUMENT_POSITION_CONTAINED_BY) {
38        echo "-> 結果: 比較ノードが基準ノードを含んでいます (DOCUMENT_POSITION_CONTAINED_BY)。\n";
39    } elseif (($position & Dom\Document::DOCUMENT_POSITION_DISCONNECTED) === Dom\Document::DOCUMENT_POSITION_DISCONNECTED) {
40        echo "-> 結果: ノードは同じドキュメントツリーに属していません (DOCUMENT_POSITION_DISCONNECTED)。\n";
41    } elseif ($position === 0) {
42        echo "-> 結果: ノードは同じノードです。\n";
43    } else {
44        echo "-> 結果: その他の関係性です。\n";
45    }
46    echo "--------------------------------------------------\n\n";
47}
48
49// Dom\Document のインスタンスを作成し、簡単なHTMLコンテンツをロードします。
50$document = new Dom\Document();
51// XML宣言がないHTMLをロードするためには loadHTML() を使用します。
52$document->loadHTML('
53    <div id="container">
54        <p id="first-child">最初の段落</p>
55        <span id="second-child">二番目の要素</span>
56    </div>
57    <div id="next-sibling">次の兄弟要素</div>
58');
59
60// 比較対象のノードをIDで取得します。
61// getElementById は Dom\Element または null を返すため、型チェックが推奨されます。
62$containerNode = $document->getElementById('container');
63$firstChildNode = $document->getElementById('first-child');
64$secondChildNode = $document->getElementById('second-child');
65$nextSiblingNode = $document->getElementById('next-sibling');
66
67// 取得したノードがすべて Dom\Element のインスタンスであることを確認します。
68if (
69    $containerNode instanceof Dom\Element &&
70    $firstChildNode instanceof Dom\Element &&
71    $secondChildNode instanceof Dom\Element &&
72    $nextSiblingNode instanceof Dom\Element
73) {
74    // 様々なノード位置関係のパターンを試します。
75
76    // 1. ノードが後に続く場合 (DOCUMENT_POSITION_FOLLOWING)
77    // '最初の段落' の後に '二番目の要素' が続く
78    compareAndDescribeDomPosition($firstChildNode, $secondChildNode);
79    // '二番目の要素' の後に '次の兄弟要素' が続く
80    compareAndDescribeDomPosition($secondChildNode, $nextSiblingNode);
81
82    // 2. ノードが前に来る場合 (DOCUMENT_POSITION_PRECEDING)
83    // '二番目の要素' の前に '最初の段落' が来る
84    compareAndDescribeDomPosition($secondChildNode, $firstChildNode);
85
86    // 3. 基準ノードが比較ノードを含んでいる場合 (DOCUMENT_POSITION_CONTAINS)
87    // 'container' が '最初の段落' を含んでいる
88    compareAndDescribeDomPosition($containerNode, $firstChildNode);
89
90    // 4. 基準ノードが比較ノードに含められている場合 (DOCUMENT_POSITION_CONTAINED_BY)
91    // '最初の段落' が 'container' に含められている
92    compareAndDescribeDomPosition($firstChildNode, $containerNode);
93} else {
94    echo "警告: 必要なDOMノードのいずれかの取得に失敗しました。HTMLのIDを確認してください。\n";
95}

このPHPサンプルコードは、DOM（Document Object Model）における二つのノード間の位置関係を比較し、特にDom\Document::DOCUMENT_POSITION_FOLLOWING定数の使われ方を初心者向けに示しています。

Dom\Document::DOCUMENT_POSITION_FOLLOWINGはPHP 8のDOM拡張機能で提供される定数の一つで、整数値を持っています。この定数は、あるノード（基準ノード）から見て、別のノード（比較ノード）がその後に続いている関係性を示す際に使用されます。

サンプルコードでは、まずcompareAndDescribeDomPositionという関数を定義しています。この関数は二つのDom\Element型のノードを引数として受け取ります。そして、基準ノードのcompareDocumentPositionメソッドを呼び出し、比較ノードとの位置関係を示すビットマスク（整数の集合値）を取得します。このメソッドが返す整数値には、様々な位置関係を表す定数（DOCUMENT_POSITION_FOLLOWINGやDOCUMENT_POSITION_PRECEDINGなど）がビットとして含まれています。

取得したビットマスクとDom\Document::DOCUMENT_POSITION_FOLLOWING定数をビット論理積（&）で比較することで、比較ノードが基準ノードの「後に続く」関係にあるかどうかを判断し、その結果を画面に出力します。この関数自体は結果を標準出力に出力するため、明示的な戻り値はありません。

コードの後半では、簡単なHTMLコンテンツを持つDom\Documentオブジェクトを作成し、複数のDOMノードを取得しています。これらのノードをcompareAndDescribeDomPosition関数に様々な組み合わせで渡すことで、「後続」「先行」「包含」といった異なる位置関係がどのように判定されるかを具体的に確認できます。これにより、DOMノード間の相対的な位置関係をプログラムで扱うための基礎的な考え方を学ぶことができます。

Dom\Document::DOCUMENT_POSITION_FOLLOWINGは、Dom\ElementのcompareDocumentPosition()メソッドの戻り値であるビットマスクに含まれる定数です。このメソッドは複数の位置関係を同時に示すため、特定の定数が結果に含まれるか確認する際には、&（ビット論理積）演算子を使って判定する必要があります。単純な等値比較（===）では意図した結果にならない場合があるためご注意ください。また、getElementById()などでノードを取得する際は、対象が存在しない場合にnullが返されることがあります。そのため、取得した変数が必ずDom\Elementのインスタンスであるかinstanceofで確認し、安全に処理を進めることが重要です。コードの可読性と保守性を高めるため、phpdocで引数や戻り値、関数の目的を記述する習慣を身につけることをお勧めします。