【PHP8.x】Dom\DocumentFragment::DOCUMENT_POSITION_PRECEDING定数の使い方

Copy
1<?php
2
3/**
4 * 2つのDOMノードの相対的な位置を比較し、
5 * 基準ノードに対して比較対象ノードが先行しているか（ドキュメントツリー上で前に位置するか）を確認します。
6 *
7 * システムエンジニアを目指す初心者向けに、Dom\Node::compareDocumentPosition() メソッドと
8 * DOCUMENT_POSITION_PRECEDING 定数の具体的な使い方を示します。
9 *
10 * @param Dom\Node $node1 比較の基準となる最初のノード
11 * @param Dom\Node $node2 比較対象の2番目のノード
12 * @return void 結果をコンソールに出力します。
13 */
14function checkNodePrecedingPosition(Dom\Node $node1, Dom\Node $node2): void
15{
16    echo "--- ノードの位置関係の比較 ---" . PHP_EOL;
17    echo "基準ノード (Node 1): <" . ($node1->nodeName ?? '不明') . ">" . PHP_EOL;
18    echo "比較対象ノード (Node 2): <" . ($node2->nodeName ?? '不明') . ">" . PHP_EOL;
19
20    // Dom\Node::compareDocumentPosition() メソッドは、2つのノード間の相対的な位置関係を示す
21    // ビットマスク（整数値）を返します。
22    // 戻り値は複数の状態を示すフラグの組み合わせであるため、ビットAND演算子 (&) を用いて特定の状態を確認します。
23    $position = $node1->compareDocumentPosition($node2);
24
25    echo "比較結果 (ビットマスク): " . $position . PHP_EOL;
26
27    // DOCUMENT_POSITION_PRECEDING 定数は、比較対象のノード (Node 2) が
28    // 基準ノード (Node 1) よりもドキュメントツリー上で前に位置することを示します。
29    //
30    // リファレンス情報ではDom\DocumentFragmentクラスに属するとされていますが、
31    // この定数は実際にはDom\Nodeクラスに定義されており、Dom\Node::DOCUMENT_POSITION_PRECEDING
32    // として利用されるのが一般的です。その値は整数値の 2 です。
33    if (($position & Dom\Node::DOCUMENT_POSITION_PRECEDING) === Dom\Node::DOCUMENT_POSITION_PRECEDING) {
34        echo "結論: 比較対象ノード (<" . ($node2->nodeName ?? '不明') . ">) は、基準ノード (<" . ($node1->nodeName ?? '不明') . ">) よりもドキュメントツリー上で「前に」位置しています。" . PHP_EOL;
35    } else {
36        echo "結論: 比較対象ノード (<" . ($node2->nodeName ?? '不明') . ">) は、基準ノード (<" . ($node1->nodeName ?? '不明') . ">) よりもドキュメントツリー上で「前に」位置していません。" . PHP_EOL;
37    }
38
39    echo PHP_EOL;
40}
41
42// 新しいDOMドキュメントを作成します。
43$document = new Dom\Document('1.0', 'UTF-8');
44$document->formatOutput = true; // 出力を整形する設定
45
46// ルート要素を作成し、ドキュメントに追加します。
47$html = $document->createElement('html');
48$document->appendChild($html);
49
50// body要素と複数のp要素、span要素を作成し、DOMツリーに追加します。
51$body = $document->createElement('body');
52$html->appendChild($body);
53
54$paragraph1 = $document->createElement('p');
55$paragraph1->textContent = '最初のパラグラフ';
56$body->appendChild($paragraph1);
57
58$span = $document->createElement('span');
59$span->textContent = 'スパン要素';
60$body->appendChild($span);
61
62$paragraph2 = $document->createElement('p');
63$paragraph2->textContent = '2番目のパラグラフ';
64$body->appendChild($paragraph2);
65
66// ここから、様々なノード間の位置関係を比較し、DOCUMENT_POSITION_PRECEDING の意味を理解します。
67
68// 例1: 後に出現するノードを基準ノードに対して比較
69// (Node 1) paragraph1 vs (Node 2) paragraph2
70// paragraph2 は paragraph1 の後に来るので、「前に」は位置しません。
71checkNodePrecedingPosition($paragraph1, $paragraph2);
72
73// 例2: 前に出現するノードを基準ノードに対して比較
74// (Node 1) paragraph2 vs (Node 2) paragraph1
75// paragraph1 は paragraph2 の前に来るので、「前に」位置します。
76checkNodePrecedingPosition($paragraph2, $paragraph1);
77
78// 例3: 親子関係（子が親の前に来るか）
79// (Node 1) body (親) vs (Node 2) paragraph1 (子)
80// paragraph1 は body の子要素であり、ドキュメントツリーの走査順序では body の「後」に評価されるため、「前に」は位置しません。
81checkNodePrecedingPosition($body, $paragraph1);
82
83// 例4: 親子関係（親が子の前に来るか）
84// (Node 1) paragraph1 (子) vs (Node 2) body (親)
85// body は paragraph1 の親要素であり、ドキュメントツリーの走査順序では paragraph1 の「前」に評価されるため、「前に」位置します。
86checkNodePrecedingPosition($paragraph1, $body);
87
88// 例5: 同じノードを比較
89// (Node 1) paragraph1 vs (Node 2) paragraph1
90// 同じノードなので、「前に」は位置しません。(比較結果には Dom\Node::DOCUMENT_POSITION_SAME_NODE がセットされます)
91checkNodePrecedingPosition($paragraph1, $paragraph1);

このPHPコードは、ウェブページの構造をプログラムで表現するDOM（Document Object Model）ツリーにおいて、二つのノードがどのような位置関係にあるかを比較する方法を説明しています。特に、あるノードが別のノードよりもドキュメントツリー上で「前に」位置しているかを確認するための、Dom\Node::compareDocumentPosition()メソッドとDOCUMENT_POSITION_PRECEDING定数の使い方を示しています。

Dom\Node::compareDocumentPosition()メソッドは、比較の基準となるノードから呼び出され、引数として比較対象のDom\Nodeを受け取ります。このメソッドの戻り値は整数値で、二つのノード間の相対的な位置関係を示す複数のフラグがビットマスクとして含まれています。

DOCUMENT_POSITION_PRECEDING定数は、この戻り値のビットマスクに含まれるフラグの一つで、比較対象のノードが基準ノードよりもドキュメントツリー上で物理的に前に位置している場合にセットされます。この定数は整数値であり、通常はDom\Node::DOCUMENT_POSITION_PRECEDINGとして利用されます。サンプルコードでは、ビットAND演算子（&）を用いて、compareDocumentPosition()の戻り値とこの定数を比較することで、比較対象ノードが前に位置しているかどうかの判定を行っています。

このコードを実行することで、親ノード、子ノード、兄弟ノードといった様々な関係にあるノード間で、どちらが「前に」位置するのかを具体的に確認でき、DOM操作におけるノードの順序や階層の理解を深めることができます。

Copy
1<?php
2
3/**
4 * 2つのDOMノード間の相対位置を比較し、
5 * 比較対象ノードが参照ノードよりも前に位置するかどうかを判断します。
6 *
7 * この関数は、DOMNode::compareDocumentPosition メソッドの戻り値と、
8 * PHP 8 で導入された Dom\DocumentFragment::DOCUMENT_POSITION_PRECEDING 定数を利用します。
9 *
10 * @param \DOMNode $referenceNode 比較の基準となるノード（参照ノード）
11 * @param \DOMNode $comparedNode  参照ノードと比較されるノード（比較対象ノード）
12 * @return bool $comparedNode が $referenceNode の前に位置する場合に true、それ以外は false
13 */
14function isPrecedingNode(\DOMNode $referenceNode, \DOMNode $comparedNode): bool
15{
16    // DOMNode::compareDocumentPosition メソッドは、
17    // 参照ノード ($referenceNode) から見た比較対象ノード ($comparedNode) の位置関係を示す
18    // ビットマスク（整数値）を返します。
19    // 例: 2つのノードが同じドキュメント内にあり、どちらも存在する場合のみ意味があります。
20    $position = $referenceNode->compareDocumentPosition($comparedNode);
21
22    // Dom\DocumentFragment::DOCUMENT_POSITION_PRECEDING 定数は、
23    // 比較対象ノードが参照ノードの「前」に位置することを示すビットフラグです。
24    // ビット論理積 (&) を使用して、返された $position に
25    // DOCUMENT_POSITION_PRECEDING フラグが含まれているかを確認します。
26    // このフラグが立っている場合、それが意味する位置関係が成立していることになります。
27    return ($position & \Dom\DocumentFragment::DOCUMENT_POSITION_PRECEDING) === \Dom\DocumentFragment::DOCUMENT_POSITION_PRECEDING;
28}
29
30// --- 単体で動作可能なサンプルコード ---
31
32// 新しいDOMDocumentを作成し、簡単なHTMLコンテンツを読み込みます。
33// loadHTML はXML宣言や不正なHTMLで警告を出すことがあるため、@で警告を抑制しています。
34$document = new \DOMDocument();
35@$document->loadHTML('
36    <!DOCTYPE html>
37    <html>
38    <head><title>DOM Position Test</title></head>
39    <body>
40        <div id="container">
41            <span id="nodeA">Node A Content</span>
42            <p id="nodeB">Node B Content</p>
43            <section id="nodeC">Node C Content</section>
44        </div>
45    </body>
46    </html>
47');
48
49// HTML要素のIDからDOMノードを取得します。
50$nodeA = $document->getElementById('nodeA');
51$nodeB = $document->getElementById('nodeB');
52$nodeC = $document->getElementById('nodeC'); // このノードはBの後に位置します。
53
54// すべてのノードが正常に取得できたか確認します。
55if ($nodeA && $nodeB && $nodeC) {
56    echo "--- DOM ノード位置比較テスト ---\n\n";
57
58    // テストケース 1: Node A (参照) と Node B (比較対象)
59    // HTML構造では Node A が Node B の前にあります。
60    // つまり、Node B は Node A の「後」に位置します。
61    // isPrecedingNode($nodeA, $nodeB) は「Node B が Node A の前に位置するか？」を判定するので、falseが期待されます。
62    echo "テスト1: Node A (参照) と Node B (比較対象)\n";
63    echo "  Node B は Node A の前に位置しますか？ " . (isPrecedingNode($nodeA, $nodeB) ? "はい" : "いいえ") . " (期待値: いいえ)\n\n";
64
65    // テストケース 2: Node B (参照) と Node A (比較対象)
66    // HTML構造では Node A が Node B の前にあります。
67    // isPrecedingNode($nodeB, $nodeA) は「Node A が Node B の前に位置するか？」を判定するので、trueが期待されます。
68    echo "テスト2: Node B (参照) と Node A (比較対象)\n";
69    echo "  Node A は Node B の前に位置しますか？ " . (isPrecedingNode($nodeB, $nodeA) ? "はい" : "いいえ") . " (期待値: はい)\n\n";
70
71    // テストケース 3: Node B (参照) と Node C (比較対象)
72    // HTML構造では Node B が Node C の前にあります。
73    // isPrecedingNode($nodeB, $nodeC) は「Node C が Node B の前に位置するか？」を判定するので、falseが期待されます。
74    echo "テスト3: Node B (参照) と Node C (比較対象)\n";
75    echo "  Node C は Node B の前に位置しますか？ " . (isPrecedingNode($nodeB, $nodeC) ? "はい" : "いいえ") . " (期待値: いいえ)\n\n";
76
77} else {
78    echo "エラー: 必要なDOMノードが見つかりませんでした。HTMLのロードまたはIDの確認をしてください。\n";
79}
80
81// 異なるドキュメントからのノードを比較する例 (disconnected)
82$anotherDocument = new \DOMDocument();
83@$anotherDocument->loadHTML('<body><div id="anotherNode">Another Node</div></body>');
84$anotherNode = $anotherDocument->getElementById('anotherNode');
85
86if ($nodeA && $anotherNode) {
87    echo "--- 異なるドキュメントノードの比較 ---\n\n";
88    // 異なるドキュメントに存在するノード同士を比較する場合、
89    // 通常は DOMNode::DOCUMENT_POSITION_DISCONNECTED フラグが立ち、
90    // DOCUMENT_POSITION_PRECEDING フラグは立たないため、false が返されます。
91    echo "テスト4: Node A (参照) と Another Node (比較対象) - 異なるドキュメント\n";
92    echo "  Another Node は Node A の前に位置しますか？ " . (isPrecedingNode($nodeA, $anotherNode) ? "はい" : "いいえ") . " (期待値: いいえ)\n\n";
93}
94

このサンプルコードは、PHPのDOM（Document Object Model）操作において、ドキュメント内の2つのHTML要素（ノード）がどのような相対位置にあるかを判定する方法を示しています。具体的には、isPrecedingNode関数を通じて、比較対象のノードが基準となるノードよりもドキュメントツリー上で「前」に位置するかどうかを真偽値で判定します。

この関数は、まずDOMNode::compareDocumentPositionメソッドを利用して、2つのノード間の位置関係を示すビットマスク（整数値）を取得します。次に、PHP 8で導入されたDom\DocumentFragment::DOCUMENT_POSITION_PRECEDING定数を使用します。この定数は、比較対象ノードが参照ノードの前に位置する場合に立つ特定のビットフラグを表します。

isPrecedingNode関数は、第一引数に比較の基準となるノード（$referenceNode）、第二引数にその基準ノードと比較されるノード（$comparedNode）を受け取ります。そして、compareDocumentPositionメソッドが返した値とDOCUMENT_POSITION_PRECEDING定数のビット論理積（&）を取り、その結果が定数と一致するかどうかを比較することで、$comparedNodeが$referenceNodeの前に位置するかを判断し、真偽値で返します。

単体で動作可能なサンプル部分では、実際にHTMLをロードして複数のノードを取得し、isPrecedingNode関数を呼び出してそれぞれの相対位置を確認しています。これにより、HTML構造上のノードの前後関係と関数の戻り値がどのように対応するかが具体的に示され、関数の挙動を理解しやすくなっています。異なるドキュメントに属するノードを比較した場合の挙動も確認できます。