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

Copy
1<?php
2
3/**
4 * DOMNode::compareDocumentPosition() メソッドを使用して、
5 * ドキュメントツリー内でのノードの位置関係を比較するサンプルです。
6 *
7 * DOCUMENT_POSITION_FOLLOWING および DOM_DOCUMENT_POSITION_PRECEDING は、
8 * 比較結果として返されるビットマスク定数であり、ノードが基準ノードよりも
9 * 前に位置するか、後に位置するかを示します。
10 *
11 * PHPでは、これらの定数はグローバル定数 (DOM_DOCUMENT_POSITION_...) として提供されます。
12 *
13 * システムエンジニアを目指す初心者の方へ:
14 * この例では、HTML構造を表現するDOMツリーから特定の要素を取得し、
15 * それらの要素がドキュメント内でどのような相対位置にあるかをプログラムで判断する方法を示します。
16 * これは、WebスクレイピングやDOM操作において要素の順序が重要な場面で役立ちます。
17 */
18function compareDomNodePositions(): void
19{
20    // 1. DOMDocumentを作成し、簡単なHTMLコンテンツをロードします。
21    //    これは、ウェブページやXMLドキュメントの構造を表現するオブジェクトです。
22    $dom = new DOMDocument();
23    // エラー表示を抑制するため、@を使用します。
24    // 無効なHTMLをロードする際に発生する警告を避けるためです。
25    @$dom->loadHTML('
26        <div id="container">
27            <span id="nodeA">最初の要素</span>
28            <p id="nodeB">中間の要素</p>
29            <strong id="nodeC">最後の要素</strong>
30        </div>
31    ');
32
33    // 2. DOMXPathオブジェクトを作成し、XPathクエリを使用して特定のノードを取得します。
34    //    XPathはXML/HTMLドキュメント内のノードを選択するための言語です。
35    $xpath = new DOMXPath($dom);
36
37    // 比較対象となるノードをIDで取得します。
38    $nodeA = $xpath->query('//*[@id="nodeA"]')->item(0); // <span id="nodeA">
39    $nodeB = $xpath->query('//*[@id="nodeB"]')->item(0); // <p id="nodeB">
40    $nodeC = $xpath->query('//*[@id="nodeC"]')->item(0); // <strong id="nodeC">
41
42    // ノードが取得できなかった場合はエラーメッセージを表示して終了します。
43    if (!$nodeA || !$nodeB || !$nodeC) {
44        echo "指定されたノードの一部が見つかりませんでした。HTML構造を確認してください。\n";
45        return;
46    }
47
48    echo "--- ノードの位置関係の比較 --- \n";
49
50    // 3. nodeBを基準にnodeAとの位置関係を比較します。
51    //    compareDocumentPosition() メソッドは、比較対象ノードが基準ノードに対して
52    //    どこに位置するかを示すビットマスクの整数値を返します。
53    $positionB_vs_A = $nodeB->compareDocumentPosition($nodeA);
54
55    echo "\nノードB ('中間の要素') と ノードA ('最初の要素') の比較:\n";
56    // DOM_DOCUMENT_POSITION_PRECEDING は、比較対象ノード($nodeA)が基準ノード($nodeB)よりも前に位置することを示します。
57    // ビットマスクなので、& 演算子を使って特定のフラグが立っているかを確認します。
58    if ($positionB_vs_A & DOM_DOCUMENT_POSITION_PRECEDING) {
59        echo "  - ノードAはノードBよりもドキュメント上で**前に**位置しています。\n";
60    }
61    // DOM_DOCUMENT_POSITION_FOLLOWING は、比較対象ノード($nodeA)が基準ノード($nodeB)よりも後に位置することを示します。
62    if ($positionB_vs_A & DOM_DOCUMENT_POSITION_FOLLOWING) {
63        echo "  - ノードAはノードBよりもドキュメント上で**後に**位置しています。\n";
64    } else {
65        // PRECENDING以外にも様々な位置関係があるため、それらのフラグが立っていない場合
66        // 今回はPRECEDINGが立つはずなので、このelseブロックには入らない想定ですが、
67        // 念のため、他の関係性を示す可能性を考慮し、条件分岐を網羅しています。
68    }
69
70    // 4. nodeBを基準にnodeCとの位置関係を比較します。
71    $positionB_vs_C = $nodeB->compareDocumentPosition($nodeC);
72
73    echo "\nノードB ('中間の要素') と ノードC ('最後の要素') の比較:\n";
74    if ($positionB_vs_C & DOM_DOCUMENT_POSITION_PRECEDING) {
75        echo "  - ノードCはノードBよりもドキュメント上で**前に**位置しています。\n";
76    }
77    if ($positionB_vs_C & DOM_DOCUMENT_POSITION_FOLLOWING) {
78        echo "  - ノードCはノードBよりもドキュメント上で**後に**位置しています。\n";
79    }
80
81    echo "\n--- その他の比較例 ---\n";
82
83    // 同じノード同士の比較 (常に0が返される)
84    $positionA_vs_A = $nodeA->compareDocumentPosition($nodeA);
85    echo "\nノードA ('最初の要素') と ノードA ('最初の要素') の比較: " . $positionA_vs_A . " (0は同じノードを意味します)\n";
86
87    // 親子関係の比較
88    $containerNode = $xpath->query('//*[@id="container"]')->item(0);
89    if ($containerNode) {
90        $positionContainer_vs_A = $containerNode->compareDocumentPosition($nodeA);
91        echo "\nコンテナノードとノードAの比較:\n";
92        // DOM_DOCUMENT_POSITION_CONTAINS は、基準ノードが比較対象ノードを含んでいることを示します。
93        if ($positionContainer_vs_A & DOM_DOCUMENT_POSITION_CONTAINS) {
94            echo "  - コンテナノードはノードAを**含んでいます**。\n";
95        }
96        // DOM_DOCUMENT_POSITION_CONTAINED_BY は、比較対象ノードが基準ノードに含まれていることを示します。
97        if ($positionContainer_vs_A & DOM_DOCUMENT_POSITION_CONTAINED_BY) {
98            echo "  - ノードAはコンテナノードに**含まれています**。\n";
99        }
100    }
101}
102
103// 関数を実行して、比較結果を表示します。
104compareDomNodePositions();
105

PHP 8で提供されるDOM関連の定数「DOCUMENT_POSITION_FOLLOWING」は、DOMツリー内のノードの位置関係を示す整数値です。この定数は、主にDOMNode::compareDocumentPosition()メソッドの戻り値として利用され、比較対象のノードが基準となるノードの後に位置していることを示します。実際のPHPコードでは、これらの定数はDOM_DOCUMENT_POSITION_FOLLOWINGのようにグローバル定数として使用されます。

compareDocumentPosition()メソッドは、引数として比較したいDOMノードを受け取り、二つのノード間の相対的な位置関係をビットマスクとして表現した整数値を返します。この戻り値には、DOM_DOCUMENT_POSITION_FOLLOWING（後に位置する）、DOM_DOCUMENT_POSITION_PRECEDING（前に位置する）、DOM_DOCUMENT_POSITION_CONTAINS（含んでいる）、DOM_DOCUMENT_POSITION_CONTAINED_BY（含まれている）などの複数の情報が含まれることがあります。

サンプルコードでは、まずHTMLコンテンツをDOMDocumentとして読み込み、特定のIDを持つノードをXPathで取得しています。その後、DOMNode::compareDocumentPosition()メソッドを使って各ノード間の位置を比較し、戻り値のビットマスクを&演算子で評価することで、どちらのノードがドキュメント上で前後に位置するかを判別しています。例えば、ノードBとノードAを比較し、結果がDOM_DOCUMENT_POSITION_PRECEDINGを含んでいれば、ノードAがノードBよりも前に存在することを意味します。

この機能は、Webスクレイピングで特定の情報の順序を保証したり、動的なDOM操作で要素の挿入位置を正確に判断したりするなど、Webアプリケーション開発において要素の相対位置が重要な場面で役立ちます。

Copy
1<?php
2
3/**
4 * DOMノードの位置関係を示す定数 Dom\Node::DOCUMENT_POSITION_FOLLOWING の利用例。
5 *
6 * この定数は、Dom\Node::compareDocumentPosition() メソッドから返されるビットマスクの一部で、
7 * あるノードが別のノードの後（following）に位置する場合を示します。
8 * (例: 子ノード、後続の兄弟ノード、子孫ノードなど)。
9 *
10 * @see \DOMNode::compareDocumentPosition()
11 * @see \DOMNode::DOCUMENT_POSITION_FOLLOWING
12 * @return void
13 * @phpstan-return void
14 */
15function demonstrateDocumentPositionFollowing(): void
16{
17    // 新しいDOMドキュメントを作成します。
18    $dom = new DOMDocument();
19
20    // 各要素を作成し、親子関係を構築します。
21    // ツリー構造の例:
22    // root
23    //   |- parent
24    //        |- child1
25    //        |- child2 (child1 の後続兄弟ノード)
26    $root = $dom->createElement('root');
27    $dom->appendChild($root);
28
29    $parent = $dom->createElement('parent');
30    $root->appendChild($parent);
31
32    $child1 = $dom->createElement('child1');
33    $parent->appendChild($child1);
34
35    $child2 = $dom->createElement('child2');
36    $parent->appendChild($child2);
37
38    echo "--- Dom\\Node::DOCUMENT_POSITION_FOLLOWING のデモンストレーション ---" . PHP_EOL;
39    echo "定数 Dom\\Node::DOCUMENT_POSITION_FOLLOWING の値: " . Dom\Node::DOCUMENT_POSITION_FOLLOWING . PHP_EOL . PHP_EOL;
40
41    // 例1: 子ノードと親ノードの比較 (child1 が parent の後に位置する)
42    // compareDocumentPosition は、参照ノードに対するターゲットノードの位置を示すビットマスクを返します。
43    // DOCUMENT_POSITION_FOLLOWING は、ターゲットノードが参照ノードの後続である場合にセットされるビットです。
44    $positionChildToParent = $parent->compareDocumentPosition($child1);
45    echo "要素 'child1' が 'parent' の後方 ('following') にあるか確認:" . PHP_EOL;
46    echo "  compareDocumentPosition() の結果: " . $positionChildToParent . PHP_EOL;
47    // ビットAND演算子 (&) を使用して、返された値に DOCUMENT_POSITION_FOLLOWING が含まれているかチェックします。
48    if (($positionChildToParent & Dom\Node::DOCUMENT_POSITION_FOLLOWING) === Dom\Node::DOCUMENT_POSITION_FOLLOWING) {
49        echo "  -> はい、'child1' は 'parent' の後に位置します。" . PHP_EOL;
50    } else {
51        echo "  -> いいえ、'child1' は 'parent' の後に位置しません。" . PHP_EOL;
52    }
53    echo PHP_EOL;
54
55    // 例2: 兄弟ノードの比較 (child2 が child1 の後に位置する)
56    $positionChild2ToChild1 = $child1->compareDocumentPosition($child2);
57    echo "要素 'child2' が 'child1' の後方 ('following') にあるか確認:" . PHP_EOL;
58    echo "  compareDocumentPosition() の結果: " . $positionChild2ToChild1 . PHP_EOL;
59    if (($positionChild2ToChild1 & Dom\Node::DOCUMENT_POSITION_FOLLOWING) === Dom\Node::DOCUMENT_POSITION_FOLLOWING) {
60        echo "  -> はい、'child2' は 'child1' の後に位置します。" . PHP_EOL;
61    } else {
62        echo "  -> いいえ、'child2' は 'child1' の後に位置しません。" . PHP_EOL;
63    }
64    echo PHP_EOL;
65
66    // 例3: 逆方向の比較 (parent が child1 の後に位置しない)
67    // 親ノードは子ノードの「前」に位置するため、DOCUMENT_POSITION_FOLLOWING はセットされません。
68    $positionParentToChild = $child1->compareDocumentPosition($parent);
69    echo "要素 'parent' が 'child1' の後方 ('following') にあるか確認:" . PHP_EOL;
70    echo "  compareDocumentPosition() の結果: " . $positionParentToChild . PHP_EOL;
71    if (($positionParentToChild & Dom\Node::DOCUMENT_POSITION_FOLLOWING) === Dom\Node::DOCUMENT_POSITION_FOLLOWING) {
72        echo "  -> はい、'parent' は 'child1' の後に位置します。" . PHP_EOL;
73    } else {
74        echo "  -> いいえ、'parent' は 'child1' の後に位置しません。" . PHP_EOL;
75    }
76}
77
78// 上記で定義したサンプル関数を実行します。
79demonstrateDocumentPositionFollowing();
80

PHPのDom\Node::DOCUMENT_POSITION_FOLLOWING定数は、XMLやHTMLドキュメントの構造を表すDOMツリーにおいて、ノード間の位置関係を判断するために利用される定数です。この定数はint型の値を持っており、あるノードが別のノードの後方（following）に位置することを示します。例えば、子ノードは親ノードの後方、後続の兄弟ノードは先行する兄弟ノードの後方に位置すると判断されます。

この定数の主な使い方は、Dom\Node::compareDocumentPosition()メソッドと組み合わせる方法です。compareDocumentPosition()メソッドは、比較対象のノードが基準となるノードに対してどこに位置するかを、複数の位置情報を示すビットマスク（int型の値）として返します。DOCUMENT_POSITION_FOLLOWINGをこのビットマスクとビットAND演算子（&）で比較することで、比較対象ノードが基準ノードの後方にあるかを正確に判定できます。

サンプルコードでは、まずDOMDocumentを作成し、「root」→「parent」→「child1」、「child2」というシンプルなDOMツリーを構築しています。parentノードとchild1ノードを比較すると、child1がparentの子ノードであるため、compareDocumentPosition()の結果にDOCUMENT_POSITION_FOLLOWINGが含まれます。同様に、child1とchild2を比較すると、child2がchild1の後続の兄弟ノードであるため、定数が一致します。一方、child1とparentを逆の順序で比較した場合、parentはchild1の後方には位置しないため、DOCUMENT_POSITION_FOLLOWINGは含まれないことが確認できます。このように、この定数を利用することで、DOMツリー内の複雑なノード位置をプログラムで効率的に判断できるようになります。