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

Copy
1<?php
2
3// PHP 8.2以降の新しいDOM拡張の名前空間を利用します。
4// Dom\Node::DOCUMENT_POSITION_FOLLOWING 定数は、この名前空間経由で参照可能です。
5// それ以前のPHP 8.xバージョンでは DOMNode::DOCUMENT_POSITION_FOLLOWING を使用します。
6use Dom\Node;
7
8/**
9 * 2つのDOMノード間の位置関係を比較し、その結果を出力する関数です。
10 * Dom\Node::compareDocumentPosition() メソッドを使用し、
11 * 主に Dom\Node::DOCUMENT_POSITION_FOLLOWING と Dom\Node::DOCUMENT_POSITION_PRECEDING 定数を用いて、
12 * ノードがドキュメント内で互いに先行するか後続するかを判断します。
13 */
14function compareDomNodePositions(): void
15{
16    // テスト用のHTMLドキュメントを作成します。
17    $dom = new DOMDocument();
18    // HTMLの読み込みで発生する可能性のある警告を抑制します。
19    libxml_use_internal_errors(true);
20    $dom->loadHTML('
21        <div id="parent">
22            <span id="child1">Child 1</span>
23            <strong id="child2">Child 2</strong>
24        </div>
25    ');
26    // エラー情報をクリアします。
27    libxml_clear_errors();
28
29    // XPathを使って比較対象のノードを確実に取得します。
30    $xpath = new DOMXPath($dom);
31    $parent = $xpath->query('//div[@id="parent"]')->item(0);
32    $child1 = $xpath->query('//span[@id="child1"]')->item(0);
33    $child2 = $xpath->query('//strong[@id="child2"]')->item(0);
34
35    // ノードが取得できなかった場合は処理を中断します。
36    if (!$parent || !$child1 || !$child2) {
37        echo "テストに必要なDOMノードが見つかりませんでした。\n";
38        return;
39    }
40
41    echo "--- DOMノード間の位置比較の例 ---\n";
42
43    // ----------------------------------------------------
44    // 例1: 'child1' (子ノード) から 'parent' (親ノード) を比較
45    // ドキュメントの論理順序では 'parent' が 'child1' より先行します。
46    // そのため、'child1' から見て 'parent' は '先行' に位置し、かつ 'parent' に '含まれて' います。
47    echo "\n[ 'child1' ノードから 'parent' ノードを比較する場合 ]\n";
48    $result1 = $child1->compareDocumentPosition($parent);
49    echo "  比較結果コード: " . $result1 . " (これはビットマスクの合計値です)\n";
50
51    if ($result1 & Node::DOCUMENT_POSITION_FOLLOWING) {
52        echo "  - 'child1' は 'parent' のドキュメント順序で『後続』にあります。\n";
53    }
54    if ($result1 & Node::DOCUMENT_POSITION_PRECEDING) {
55        echo "  - 'child1' は 'parent' のドキュメント順序で『先行』にあります。\n";
56    }
57    if ($result1 & Node::DOCUMENT_POSITION_CONTAINS) {
58        echo "  - 'child1' は 'parent' を『含んで』います。\n";
59    }
60    if ($result1 & Node::DOCUMENT_POSITION_CONTAINED_BY) {
61        echo "  - 'child1' は 'parent' に『含まれて』います。\n";
62    }
63    if ($result1 === 0) {
64        echo "  - 両ノードは同じノードです。\n";
65    }
66
67    // ----------------------------------------------------
68    // 例2: 'parent' (親ノード) から 'child1' (子ノード) を比較
69    // ドキュメントの論理順序では 'parent' が 'child1' より先行します。
70    // そのため、'parent' から見て 'child1' は '後続' に位置し、かつ 'parent' が 'child1' を '含んで' います。
71    echo "\n[ 'parent' ノードから 'child1' ノードを比較する場合 ]\n";
72    $result2 = $parent->compareDocumentPosition($child1);
73    echo "  比較結果コード: " . $result2 . "\n";
74
75    if ($result2 & Node::DOCUMENT_POSITION_FOLLOWING) {
76        echo "  - 'parent' は 'child1' のドキュメント順序で『後続』にあります。\n";
77    }
78    if ($result2 & Node::DOCUMENT_POSITION_PRECEDING) {
79        echo "  - 'parent' は 'child1' のドキュメント順序で『先行』にあります。\n";
80    }
81    if ($result2 & Node::DOCUMENT_POSITION_CONTAINS) {
82        echo "  - 'parent' は 'child1' を『含んで』います。\n";
83    }
84    if ($result2 & Node::DOCUMENT_POSITION_CONTAINED_BY) {
85        echo "  - 'parent' は 'child1' に『含まれて』います。\n";
86    }
87    if ($result2 === 0) {
88        echo "  - 両ノードは同じノードです。\n";
89    }
90
91    // ----------------------------------------------------
92    // 例3: 'child1' (兄弟ノード) から 'child2' (兄弟ノード) を比較
93    // ドキュメントの論理順序では 'child1' が 'child2' より先行します。
94    // そのため、'child1' から見て 'child2' は『後続』に位置します。
95    echo "\n[ 'child1' ノードから 'child2' ノードを比較する場合 (兄弟ノード) ]\n";
96    $result3 = $child1->compareDocumentPosition($child2);
97    echo "  比較結果コード: " . $result3 . "\n";
98
99    if ($result3 & Node::DOCUMENT_POSITION_FOLLOWING) {
100        echo "  - 'child1' は 'child2' のドキュメント順序で『後続』にあります。\n";
101    }
102    if ($result3 & Node::DOCUMENT_POSITION_PRECEDING) {
103        echo "  - 'child1' は 'child2' のドキュメント順序で『先行』にあります。\n";
104    }
105    // 兄弟ノードは互いに含み合わないため、通常以下の条件は真になりません。
106    if ($result3 & Node::DOCUMENT_POSITION_CONTAINS) {
107        echo "  - 'child1' は 'child2' を『含んで』います。\n";
108    }
109    if ($result3 & Node::DOCUMENT_POSITION_CONTAINED_BY) {
110        echo "  - 'child1' は 'child2' に『含まれて』います。\n";
111    }
112    if ($result3 === 0) {
113        echo "  - 両ノードは同じノードです。\n";
114    }
115}
116
117// 定義した関数を実行し、DOMノードの位置関係を比較します。
118compareDomNodePositions();

このサンプルコードは、PHPでHTMLやXMLドキュメントを操作する際に使われるDOM拡張の機能を紹介しています。特に、Dom\Node::DOCUMENT_POSITION_FOLLOWING定数に焦点を当て、ドキュメント内の2つのノードが互いにどのような位置関係にあるかを判断する方法を示しています。

Dom\Node::DOCUMENT_POSITION_FOLLOWING定数は、あるノードが比較対象の別のノードよりもドキュメントの論理的な順序で「後続」している、つまり後に出現する位置にあることを示す整数値です。この定数自体は引数を取りませんが、主にDom\NodeクラスのcompareDocumentPosition()メソッドの戻り値を解釈するために使用されます。

compareDocumentPosition()メソッドは、引数として比較したい別のノードを受け取ります。このメソッドの戻り値は整数値で、これは複数の位置関係を示すフラグ（ビットマスク）を組み合わせたものです。例えば、DOCUMENT_POSITION_FOLLOWINGの他に、DOCUMENT_POSITION_PRECEDING（先行する）、DOCUMENT_POSITION_CONTAINS（含む）、DOCUMENT_POSITION_CONTAINED_BY（含まれる）といった定数があります。サンプルコードでは、これらの定数をビット論理積演算子（&）と組み合わせて、戻り値がどの位置関係を示しているかを具体的に判別しています。

コードは、親ノードと子ノード、あるいは兄弟ノードといった様々な関係のノードを生成し、それぞれの間でcompareDocumentPosition()メソッドを呼び出しています。その結果を分析することで、ノードが後続しているか、先行しているか、互いに含み合っているかといった詳細な位置関係を初心者の方にもわかりやすく示しています。これにより、ドキュメント構造を解析したり、特定の要素の相対位置に基づいて処理を行ったりする際の基本的な知識を学ぶことができます。

Copy
1<?php
2
3/**
4 * 2つのDOMノード間の位置関係を比較し、
5 * 第2引数のノードが第1引数のノードに「続く」関係にあるかを判断します。
6 *
7 * この関数は、`\DOMNode::compareDocumentPosition()` メソッドを使用し、
8 * 定数 `\DOMNode::DOCUMENT_POSITION_FOLLOWING` とビット演算子を用いて比較します。
9 * システムエンジニアを目指す初心者の方にも、DOMノードの比較方法と
10 * ビットマスク定数の活用例を理解してもらうことを目的としています。
11 *
12 * @param \DOMNode $node1 比較の基準となる最初のDOMノード。
13 * @param \DOMNode $node2 比較される2番目のDOMノード。
14 * @return bool `node2` が `node1` のドキュメント順序で後に続く場合、`true`を返します。それ以外の場合は`false`。
15 */
16function checkNodeIsFollowing(\DOMNode $node1, \DOMNode $node2): bool
17{
18    // compareDocumentPosition() メソッドは、2つのノード間の位置関係を
19    // ビットマスクとして表現した整数値を返します。
20    $position = $node1->compareDocumentPosition($node2);
21
22    // Dom\Node::DOCUMENT_POSITION_FOLLOWING 定数（PHP 8では \DOMNode::DOCUMENT_POSITION_FOLLOWING に相当）は、
23    // 第2引数のノードが第1引数のノードの後に続くことを示します。
24    // ビットマスクであるため、ビット論理AND演算子 (&) を使用して、
25    // 返された $position 値にこのフラグが含まれているかを確認します。
26    return ($position & \DOMNode::DOCUMENT_POSITION_FOLLOWING) === \DOMNode::DOCUMENT_POSITION_FOLLOWING;
27}
28
29// 以下は、上記の関数が単体で動作することを示すための実行例です。
30// HTML文字列からDOMドキュメントを構築します。
31$dom = new \DOMDocument();
32// HTMLパース時の警告を抑制するために libxml_use_internal_errors を一時的に設定します。
33libxml_use_internal_errors(true);
34$dom->loadHTML('<html><body><div id="parent"><p id="first">First paragraph</p><span id="second">Second span</span></div></body></html>');
35libxml_use_internal_errors(false); // エラー処理を元に戻します。
36
37// 比較対象となるDOMノードをIDで取得します。
38$firstParagraph = $dom->getElementById('first');
39$secondSpan = $dom->getElementById('second');
40$parentDiv = $dom->getElementById('parent');
41
42echo "--- DOM ノード位置関係の比較 ---" . PHP_EOL;
43
44if ($firstParagraph && $secondSpan) {
45    // 例1: 'secondSpan' (ID: "second") が 'firstParagraph' (ID: "first") の後に続くか？
46    // HTML構造上、<span> タグは <p> タグの後に記述されているため、結果は true となります。
47    $isSecondFollowingFirst = checkNodeIsFollowing($firstParagraph, $secondSpan);
48    echo "ノード 'second' は ノード 'first' に続いていますか？ " . ($isSecondFollowingFirst ? 'はい' : 'いいえ') . PHP_EOL;
49
50    // 例2: 'firstParagraph' (ID: "first") が 'secondSpan' (ID: "second") の後に続くか？
51    // HTML構造上、<p> タグは <span> タグの前に記述されているため、結果は false となります。
52    $isFirstFollowingSecond = checkNodeIsFollowing($secondSpan, $firstParagraph);
53    echo "ノード 'first' は ノード 'second' に続いていますか？ " . ($isFirstFollowingSecond ? 'はい' : 'いいえ') . PHP_EOL;
54} else {
55    echo "必要なDOMノードが見つかりませんでした。HTMLのIDを確認してください。" . PHP_EOL;
56}
57
58if ($parentDiv && $firstParagraph) {
59    // 例3: 'firstParagraph' (ID: "first") が 'parentDiv' (ID: "parent") の後に続くか？
60    // 'firstParagraph' は 'parentDiv' の子孫ノードであり、ドキュメント順序では親ノードの後に現れます。
61    // そのため、この場合も true となります。
62    $isFirstFollowingParent = checkNodeIsFollowing($parentDiv, $firstParagraph);
63    echo "ノード 'first' は ノード 'parent' に続いていますか？ " . ($isFirstFollowingParent ? 'はい' : 'いいえ') . PHP_EOL;
64}

このPHPサンプルコードは、WebページなどのHTML構造を表すDOM（Document Object Model）ノード間で、あるノードが別のノードの「後に続く」位置にあるかを判定する方法を示しています。具体的には、checkNodeIsFollowingという関数を定義し、2つのDOMノードの位置関係を比較します。

checkNodeIsFollowing関数は、比較の基準となる最初のDOMノードを$node1として、比較対象の2番目のDOMノードを$node2として引数に取ります。戻り値は真偽値（bool）で、$node2が$node1のドキュメント順序で物理的に後に続く位置にあればtrueを、そうでなければfalseを返します。

関数内部では、$node1オブジェクトのcompareDocumentPosition()メソッドを使って、$node1と$node2間の相対的な位置関係を示す整数値を取得します。この整数値はビットマスクと呼ばれる形式で、様々な位置関係の情報を持ちます。次に、ビット論理AND演算子（&）を用いて、取得したビットマスクに\DOMNode::DOCUMENT_POSITION_FOLLOWING定数が表す「後に続く」関係のフラグが含まれているかを確認します。この定数は、対象ノードが基準ノードのドキュメント順序で後に現れることを示します。

実行例では、実際にHTML文字列からDOMドキュメントを構築し、異なるノードペア（例えば、連続する兄弟ノードや親子ノード）に対してcheckNodeIsFollowing関数を呼び出し、その結果がHTMLの構造と一致することを確認しています。このコードを通じて、DOMノードの比較方法と、ビットマスク定数を利用した特定の状態の判定方法を理解することができます。