【PHP8.x】DOMNotation::DOCUMENT_POSITION_FOLLOWING定数の使い方

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

作成日: 2025年09月11日更新日: 2025年12月03日

基本的な使い方

DOCUMENT_POSITION_FOLLOWING定数は、DOM (Document Object Model) において、あるノードが別のノードに対してドキュメントツリー上で後続する位置にあることを示す定数です。DOMとは、HTMLやXMLといった文書の構造を、プログラムから操作できるように表現する仕組みであり、文書内の各要素やテキストなどは「ノード」として扱われ、それらが階層的な「ドキュメントツリー」を形成しています。

この定数は、主にPHPのDOM拡張機能におけるDOMNode::compareDocumentPosition()メソッドの戻り値を解釈する際に利用されます。compareDocumentPosition()メソッドは、二つのノードがドキュメントツリー上でどのような位置関係にあるかを比較し、その結果をビットマスクと呼ばれる数値で返します。例えば、比較対象のノードが、メソッドを呼び出したノードよりもドキュメントツリー上後方に位置する場合、このDOCUMENT_POSITION_FOLLOWING定数の値が戻り値のビットマスクに含まれます。

この定数を利用することで、プログラムは文書内の要素の順序を正確に判断し、特定の要素の後に続く要素を見つけ出すなど、複雑なDOM操作を行うことが可能になります。ウェブページのスクレイピングやXMLデータの解析など、文書の構造に基づいた処理を実装する上で非常に重要な役割を果たす定数の一つです。

構文(syntax)


1<?php
2
3echo DOMNotation::DOCUMENT_POSITION_FOLLOWING;

引数(parameters)

引数なし

引数はありません

戻り値(return)

int

DOMNotation::DOCUMENT_POSITION_FOLLOWING は、ノードが指定されたノードの後に位置することを示す整数値を返します。

サンプルコード

DOMノード位置比較（PRECEDING/FOLLOWING）


1<?php
2
3/**
4 * 2つのDOMノードの相対的な位置を比較するサンプル関数です。
5 * DOMNode::compareDocumentPosition() メソッドを使用し、
6 * DOMNode::DOCUMENT_POSITION_FOLLOWING と DOMNode::DOCUMENT_POSITION_PRECEDING
7 * 定数を用いて比較結果を解釈します。
8 */
9function compareDomNodesPositionExample(): void
10{
11    // DOMDocument オブジェクトを作成し、サンプルHTMLを読み込みます。
12    $dom = new DOMDocument();
13    // HTMLの構文エラーを抑制するため、LIBXML_NOWARNING を使用することがあります。
14    @$dom->loadHTML('
15        <html>
16            <body>
17                <div id="container">
18                    <p id="first-paragraph">これは最初の段落です。</p>
19                    <span id="target-span">これは比較対象のSPAN要素です。</span>
20                    <p id="second-paragraph">これは2番目の段落です。</p>
21                </div>
22            </body>
23        </html>
24    ');
25
26    // 比較対象となるノードを取得します。
27    // getElementById は DOMDocument または DOMElement から呼び出せます。
28    $firstParagraph = $dom->getElementById('first-paragraph');
29    $targetSpan = $dom->getElementById('target-span');
30    $secondParagraph = $dom->getElementById('second-paragraph');
31
32    // ノードが正常に取得できたか確認します。
33    if ($firstParagraph === null || $targetSpan === null || $secondParagraph === null) {
34        echo "エラー: 必要なノードが見つかりませんでした。\n";
35        return;
36    }
37
38    echo "--- target-span と他のノードの位置を比較 --- \n\n";
39
40    // ケース1: targetSpan から見て firstParagraph の位置を比較します。
41    // (firstParagraph は targetSpan の前に位置します)
42    $positionRelativeToFirst = $targetSpan->compareDocumentPosition($firstParagraph);
43
44    echo "target-span から見た first-paragraph の位置:\n";
45    // DOCUMENT_POSITION_PRECEDING は、比較対象ノード (firstParagraph) が
46    // 参照ノード (targetSpan) より前に位置することを示します。
47    if (($positionRelativeToFirst & DOMNode::DOCUMENT_POSITION_PRECEDING) === DOMNode::DOCUMENT_POSITION_PRECEDING) {
48        echo "  -> first-paragraph は target-span より前に位置しています。\n";
49    }
50    // DOCUMENT_POSITION_FOLLOWING は、比較対象ノードが参照ノードより後に位置することを示します。
51    if (($positionRelativeToFirst & DOMNode::DOCUMENT_POSITION_FOLLOWING) === DOMNode::DOCUMENT_POSITION_FOLLOWING) {
52        echo "  -> first-paragraph は target-span より後に位置しています。\n";
53    }
54    echo "\n";
55
56    // ケース2: targetSpan から見て secondParagraph の位置を比較します。
57    // (secondParagraph は targetSpan の後に位置します)
58    $positionRelativeToSecond = $targetSpan->compareDocumentPosition($secondParagraph);
59
60    echo "target-span から見た second-paragraph の位置:\n";
61    if (($positionRelativeToSecond & DOMNode::DOCUMENT_POSITION_PRECEDING) === DOMNode::DOCUMENT_POSITION_PRECEDING) {
62        echo "  -> second-paragraph は target-span より前に位置しています。\n";
63    }
64    // ここでは DOCUMENT_POSITION_FOLLOWING が期待されます。
65    if (($positionRelativeToSecond & DOMNode::DOCUMENT_POSITION_FOLLOWING) === DOMNode::DOCUMENT_POSITION_FOLLOWING) {
66        echo "  -> second-paragraph は target-span より後に位置しています。\n";
67    }
68    echo "\n";
69}
70
71// 関数を実行します。
72compareDomNodesPositionExample();

このPHPのサンプルコードは、HTML文書内の2つのDOMノードが互いに対してどのような相対位置にあるかを比較する方法を示しています。具体的には、DOMNode::compareDocumentPosition()メソッドを使用し、その戻り値とDOMNode::DOCUMENT_POSITION_FOLLOWING、DOMNode::DOCUMENT_POSITION_PRECEDINGといった定数を用いて結果を解釈します。

DOMNode::DOCUMENT_POSITION_FOLLOWING定数は引数を取らず、整数値を返します。これは、比較対象のノードが参照ノードの「後に位置する」ことを示すビットフラグの値です。同様に、DOMNode::DOCUMENT_POSITION_PRECEDINGも引数を取らず整数値を返し、比較対象ノードが参照ノードの「前に位置する」ことを示します。

サンプルコードでは、まずDOMDocumentを作成し、簡単なHTMLコンテンツを読み込んでいます。次に、getElementById()メソッドで特定のHTML要素（first-paragraph、target-span、second-paragraph）を取得します。

その後、target-spanを基準ノードとして、他のノードとの位置をcompareDocumentPosition()で比較します。このメソッドが返す整数値は、複数の位置情報がビットフラグとして組み合わされたものです。したがって、ビットAND演算子（&）を使って、結果にDOMNode::DOCUMENT_POSITION_FOLLOWINGやDOMNode::DOCUMENT_POSITION_PRECEDINGが含まれているかを判断することで、具体的な前後関係を判定し、その結果を出力しています。これにより、文書ツリー内での要素の配置をプログラムで明確に識別できます。

このサンプルコードで DOMNode::compareDocumentPosition() メソッドの戻り値は、複数の状態を同時に示すビットマスクです。そのため、特定の位置関係を確認する際は、ビットAND演算子 & を用いて定数と比較する必要があります。DOCUMENT_POSITION_FOLLOWING や DOCUMENT_POSITION_PRECEDING 以外にも、ノードの包含関係などを示す定数も存在するため、必要に応じて他の定数も理解し組み合わせて利用してください。また、DOMDocument::loadHTML() で使われているエラー抑制演算子 @ は、発生した警告を非表示にするため、デバッグを困難にする可能性があります。本番環境のコードでは、エラー抑制を避け、XML/HTMLの妥当性確認など他の方法でエラーを適切に処理することをおすすめします。ノードが取得できない場合に備え、nullチェックによるエラーハンドリングは必ず行ってください。

PHP DOMノード位置比較を行う


1<?php
2
3/**
4 * 2つのDOMノードを比較し、最初のノード ($node1) が2番目のノード ($node2) より
5 * 論理的にドキュメントツリーの前方に位置するかを判定します。
6 *
7 * DOMNode::DOCUMENT_POSITION_FOLLOWING 定数は、
8 * 比較対象のノード ($node2) が参照ノード ($node1) に続く位置にある場合、
9 * すなわち $node1 が $node2 の前に位置する場合に、
10 * DOMNode::compareDocumentPosition() メソッドによって返されるビットマスクに含まれます。
11 *
12 * @param DOMNode $node1 比較の参照となるDOMノード。
13 * @param DOMNode $node2 比較対象のDOMノード。
14 * @return bool $node1 が $node2 の前に論理的に位置する場合にtrue、そうでない場合はfalse。
15 */
16function isNodePreceding(DOMNode $node1, DOMNode $node2): bool
17{
18    // compareDocumentPosition メソッドは2つのノード間の関係をビットマスクで返します。
19    // DOCUMENT_POSITION_FOLLOWING フラグは、$node2 が $node1 に続く場合に設定されます。
20    // つまり、$node1 が $node2 の前に来る場合にこのフラグが立ちます。
21    $position = $node1->compareDocumentPosition($node2);
22
23    // ビット論理積 (&) を使って、DOCUMENT_POSITION_FOLLOWING フラグが結果に含まれているかチェックします。
24    // フラグが設定されていれば、$node1 は $node2 より前に位置します。
25    return (bool)($position & DOMNode::DOCUMENT_POSITION_FOLLOWING);
26}
27
28// --- サンプル使用例 ---
29
30// 1. DOMDocument を作成し、XMLツリーを構築します。
31$dom = new DOMDocument('1.0', 'UTF-8');
32$dom->formatOutput = true; // 出力を見やすく整形
33
34$root = $dom->createElement('root');
35$dom->appendChild($root);
36
37$elementA = $dom->createElement('elementA', '要素A');
38$root->appendChild($elementA);
39
40$elementB = $dom->createElement('elementB', '要素B');
41$root->appendChild($elementB); // elementB は elementA の後に位置します。
42
43$elementC = $dom->createElement('elementC', '要素C');
44$elementB->appendChild($elementC); // elementC は elementB の子で、elementA よりも後に位置します。
45
46// 2. 構築したノードを使用して、位置関係を比較します。
47echo "--- DOM ノード位置比較 ---" . PHP_EOL;
48
49// elementA と elementB の比較: elementA は elementB の前に位置するか？ (期待値: true)
50if (isNodePreceding($elementA, $elementB)) {
51    echo "要素 'elementA' は要素 'elementB' の前に位置します。" . PHP_EOL;
52} else {
53    echo "要素 'elementA' は要素 'elementB' の前に位置しません。" . PHP_EOL;
54}
55
56// elementB と elementA の比較: elementB は elementA の前に位置するか？ (期待値: false)
57if (isNodePreceding($elementB, $elementA)) {
58    echo "要素 'elementB' は要素 'elementA' の前に位置します。" . PHP_EOL;
59} else {
60    echo "要素 'elementB' は要素 'elementA' の前に位置しません。" . PHP_EOL;
61}
62
63// elementA と elementC の比較: elementA は elementC の前に位置するか？ (期待値: true)
64if (isNodePreceding($elementA, $elementC)) {
65    echo "要素 'elementA' は要素 'elementC' の前に位置します。" . PHP_EOL;
66} else {
67    echo "要素 'elementA' は要素 'elementC' の前に位置しません。" . PHP_EOL;
68}
69
70// 同じノード同士の比較: elementA は elementA の前に位置するか？ (期待値: false)
71// DOCUMENT_POSITION_FOLLOWING は自身のノードに対しては設定されません。
72if (isNodePreceding($elementA, $elementA)) {
73    echo "要素 'elementA' は自身の前に位置します。" . PHP_EOL;
74} else {
75    echo "要素 'elementA' は自身の前に位置しません。" . PHP_EOL;
76}
77
78echo PHP_EOL;
79echo "--- 構築されたXML ---" . PHP_EOL;
80echo $dom->saveXML();
81

このPHPコードは、XMLなどのDOM（Document Object Model）ツリーにおいて、あるノードが別のノードよりドキュメントツリー上で「前に位置するか」を判定する方法を示しています。

isNodePreceding関数は、比較対象となる2つのDOMNodeオブジェクト（$node1と$node2）を受け取ります。この関数は、$node1が$node2より前に位置する場合にtrueを、そうでない場合にfalseを返します。

内部では、DOMNodeクラスのcompareDocumentPositionメソッドを利用し、2つのノード間の関係を示すビットマスクという整数値を取得します。このビットマスクには、$node2が$node1の後に続く位置にある場合に設定されるDOMNode::DOCUMENT_POSITION_FOLLOWINGというフラグが含まれます。このフラグがビットマスクに含まれているかをビット論理積&演算子で確認することで、$node1が$node2より前に位置するかどうかを判定しています。

サンプルコードでは、XML要素を構築し、異なるノードの組み合わせでisNodePreceding関数を呼び出すことで、DOMツリー内でのノードの位置関係が正しく判定される様子が示されており、DOM操作の理解に役立ちます。

DOMNode::compareDocumentPosition()メソッドは、ノード間の多様な関係を一つの整数（ビットマスク）で表現します。このビットマスクから特定の関係を抽出するには、ビット論理積演算子 (&) を用いて目的の定数（DOMNode::DOCUMENT_POSITION_FOLLOWINGなど）と比較する理解が重要です。DOCUMENT_POSITION_FOLLOWING定数は、比較対象ノードが参照ノードの「後に続く」場合に設定されるフラグです。したがって、このフラグが立っている場合は、参照ノードが比較対象ノードの「前に位置する」ことを意味します。この関係性を正確に把握し、関数の意図と合わせて理解することが、コードを正しく利用するための注意点です。DOMツリーの構造とノードの相対的な位置関係を意識して利用してください。