【PHP8.x】DOMEntity::DOCUMENT_POSITION_PRECEDING定数の使い方

Copy
1<?php
2
3/**
4 * DOMNode::DOCUMENT_POSITION_PRECEDING 定数の使用例を示します。
5 *
6 * この定数は、DOMNode::compareDocumentPosition() メソッドが返すビットマスクの一部であり、
7 * 比較対象のノードが参照元のノードより前にドキュメント内で位置することを示します。
8 * DOMEntity も DOMNode を継承しているため、同様にこの定数を利用できますが、
9 * 通常は DOMElement などのより一般的なノード間で位置関係を比較する際に使用されます。
10 */
11function demonstrateDocumentPositionPreceding(): void
12{
13    // 新しい DOMDocument を作成し、サンプルHTMLを読み込む
14    $dom = new DOMDocument();
15    // HTMLのパースエラーを抑制 (本番環境では適切なエラーハンドリングを推奨)
16    @$dom->loadHTML('<div><p id="node-a">ノードA</p><span id="node-b">ノードB</span></div>');
17
18    // 比較対象となる2つのノードを取得
19    // DOMElement は DOMNode を継承しています。
20    $nodeA = $dom->getElementById('node-a'); // ドキュメント内で先に現れるノード
21    $nodeB = $dom->getElementById('node-b'); // ドキュメント内で後に現れるノード
22
23    if ($nodeA && $nodeB) {
24        echo "ノードA (id='node-a') と ノードB (id='node-b') の位置関係を比較します。\n\n";
25
26        // ノードBからノードAの位置を比較する
27        // ノードAはノードBよりもドキュメント内で「前」に位置するため、
28        // compareDocumentPosition の結果に DOMNode::DOCUMENT_POSITION_PRECEDING が含まれます。
29        $positionFromBtoA = $nodeB->compareDocumentPosition($nodeA);
30        echo "ノードAの位置 (ノードBから見て): " . $positionFromBtoA . " (ビットマスク値)\n";
31
32        // DOMNode::DOCUMENT_POSITION_PRECEDING 定数 (値は通常 4) と結果をビットANDで比較
33        if ($positionFromBtoA & DOMNode::DOCUMENT_POSITION_PRECEDING) {
34            echo "  - 結果には DOMNode::DOCUMENT_POSITION_PRECEDING が含まれています。\n";
35            echo "  - これは、ノードAがノードBよりもドキュメント内で「前」に位置することを示します。\n";
36        } else {
37            echo "  - 結果には DOMNode::DOCUMENT_POSITION_PRECEDING は含まれていません。\n";
38        }
39
40        echo "\n----------------------------------------\n\n";
41
42        // 逆に、ノードAからノードBの位置を比較する
43        // ノードBはノードAよりもドキュメント内で「後」に位置するため、
44        // 結果に DOMNode::DOCUMENT_POSITION_PRECEDING は含まれません。
45        $positionFromAtoB = $nodeA->compareDocumentPosition($nodeB);
46        echo "ノードBの位置 (ノードAから見て): " . $positionFromAtoB . " (ビットマスク値)\n";
47
48        if ($positionFromAtoB & DOMNode::DOCUMENT_POSITION_PRECEDING) {
49            echo "  - 結果には DOMNode::DOCUMENT_POSITION_PRECEDING が含まれています。\n";
50            echo "  - これは、ノードBがノードAよりもドキュメント内で「前」に位置することと矛盾します。\n";
51        } else {
52            echo "  - 結果には DOMNode::DOCUMENT_POSITION_PRECEDING は含まれていません。\n";
53            echo "  - これは、ノードBがノードAよりもドキュメント内で「後」に位置することと一致します。\n";
54        }
55
56    } else {
57        echo "比較対象のノードが見つかりませんでした。HTMLのIDを確認してください。\n";
58    }
59}
60
61// 関数を実行してサンプルコードの動作を確認
62demonstrateDocumentPositionPreceding();

PHPのDOMNode::DOCUMENT_POSITION_PRECEDING定数は、DOM（Document Object Model）ツリー内のノードの位置関係をプログラムで判断するために使用されます。この定数は、あるノードが別のノードよりドキュメント内で「前」に位置するかどうかを示すビットマスク値です。

具体的には、DOMNode::compareDocumentPosition()メソッドの戻り値を評価する際に活用されます。compareDocumentPosition()メソッドは、比較対象のノードと参照元のノードの間の複数の位置関係をビットマスクとして返しますが、その結果にDOCUMENT_POSITION_PRECEDINGが含まれる場合、比較対象のノードが参照元のノードよりもドキュメント内で物理的に前に存在することを意味します。

サンプルコードでは、まずHTMLドキュメントを読み込み、「node-a」と「node-b」という2つのノードを取得しています。nodeBからnodeAの位置を比較する際に、nodeAがnodeBより前に位置するため、compareDocumentPosition()の戻り値にはDOMNode::DOCUMENT_POSITION_PRECEDING定数が示すビットが含まれています。この有無は、結果と定数をビットAND演算子（&）で比較することで確認できます。逆にnodeAからnodeBの位置を比較すると、nodeBはnodeAより後に位置するため、この定数は結果に含まれません。

この定数自体には引数や戻り値はありませんが、compareDocumentPosition()メソッドの戻り値と組み合わせることで、Webページ上の要素の相対的な順序を正確に判別し、JavaScriptのようなDOM操作をPHPで実現する際に非常に役立ちます。

Copy
1<?php
2
3/**
4 * 2つのDOMノード間の位置関係を比較し、結果を分かりやすく説明する関数。
5 *
6 * この関数は、DOMNode::compareDocumentPosition() メソッドを利用して、
7 * 最初のノードから見て2番目のノードがどのような位置関係にあるかを判定します。
8 * 特に、DOMNode::DOCUMENT_POSITION_PRECEDING 定数を用いて、
9 * 2番目のノードが最初のノードより「前」に位置するかどうかを詳しく報告します。
10 *
11 * @param DOMNode $node1 比較の基準となる最初のDOMノード。
12 * @param DOMNode $node2 比較対象となる2番目のDOMノード。
13 * @return string ノード間の位置関係を説明するテキストメッセージ。
14 */
15function describeNodePosition(DOMNode $node1, DOMNode $node2): string
16{
17    // compareDocumentPosition() メソッドは、2つのノード間の相対的な位置関係を示すビットマスクを返します。
18    // この戻り値は、複数の定数の組み合わせである可能性があるため、ビット論理AND演算子 (&) で比較します。
19    $positionResult = $node1->compareDocumentPosition($node2);
20
21    $node1Name = $node1->nodeName ?? '不明なノード1';
22    $node2Name = $node2->nodeName ?? '不明なノード2';
23    $description = "ノード '{$node1Name}' とノード '{$node2Name}' の位置関係:\n";
24
25    if ($positionResult === 0) {
26        $description .= "  - 両方のノードは同じノードです。\n";
27    } else {
28        // DOCUMENT_POSITION_PRECEDING は、比較対象のノード ($node2) が基準ノード ($node1) の前に位置する場合にセットされます。
29        if ($positionResult & DOMNode::DOCUMENT_POSITION_PRECEDING) {
30            $description .= "  - ノード '{$node2Name}' はノード '{$node1Name}' より物理的に前に位置します。\n";
31        }
32        // DOCUMENT_POSITION_FOLLOWING は、比較対象のノード ($node2) が基準ノード ($node1) の後に位置する場合にセットされます。
33        if ($positionResult & DOMNode::DOCUMENT_POSITION_FOLLOWING) {
34            $description .= "  - ノード '{$node2Name}' はノード '{$node1Name}' より物理的に後に位置します。\n";
35        }
36        // DOCUMENT_POSITION_CONTAINS は、基準ノード ($node1) が比較対象のノード ($node2) を包含する場合にセットされます。
37        if ($positionResult & DOMNode::DOCUMENT_POSITION_CONTAINS) {
38            $description .= "  - ノード '{$node1Name}' はノード '{$node2Name}' を包含します。\n";
39        }
40        // DOCUMENT_POSITION_CONTAINED_BY は、比較対象のノード ($node2) が基準ノード ($node1) を包含する場合にセットされます。
41        if ($positionResult & DOMNode::DOCUMENT_POSITION_CONTAINED_BY) {
42            $description .= "  - ノード '{$node2Name}' はノード '{$node1Name}' を包含します。\n";
43        }
44        // DOCUMENT_POSITION_DISCONNECTED は、ノードが異なるツリーに存在するか、ツリー内に存在しない場合にセットされます。
45        if ($positionResult & DOMNode::DOCUMENT_POSITION_DISCONNECTED) {
46            $description .= "  - ノードは互いに接続されていません (異なるツリーにあるか、まだドキュメントに追加されていません)。\n";
47        }
48        // 他にも DOMNode::DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC などの定数がありますが、
49        // 今回は DOCUMENT_POSITION_PRECEDING を中心に、代表的なものを扱います。
50    }
51
52    return $description;
53}
54
55// === サンプルコードの実行部分 ===
56
57// 新しいDOMドキュメントを作成します。
58$dom = new DOMDocument('1.0', 'UTF-8');
59$dom->formatOutput = true; // 整形されたXML出力を有効にします
60
61// ルート要素を作成し、ドキュメントに追加します。
62$root = $dom->createElement('root');
63$dom->appendChild($root);
64
65// 子要素を作成し、ルート要素に追加します。
66$childA = $dom->createElement('childA');
67$root->appendChild($childA);
68
69// childA の子要素を作成します。
70$grandchildX = $dom->createElement('grandchildX');
71$childA->appendChild($grandchildX);
72
73// 別の直接の子要素を作成し、ルート要素に追加します。
74$childB = $dom->createElement('childB');
75$root->appendChild($childB);
76
77// さらにもう一つの子要素を作成します。
78$childC = $dom->createElement('childC');
79$root->appendChild($childC);
80
81// まだドキュメントツリーに追加されていないノードを作成します。
82$unattachedNode = $dom->createElement('unattached');
83
84echo "--- 様々なノード位置の比較例 ---\n\n";
85
86// 例 1: childB と childA の比較
87// childA (node2) は childB (node1) より前に位置します。
88echo describeNodePosition($childB, $childA);
89echo "\n";
90
91// 例 2: childA と childB の比較
92// childB (node2) は childA (node1) より後に位置します。
93echo describeNodePosition($childA, $childB);
94echo "\n";
95
96// 例 3: root と childA の比較
97// root (node1) は childA (node2) を包含します。
98// childA (node2) は root (node1) に包含されます。
99echo describeNodePosition($root, $childA);
100echo "\n";
101
102// 例 4: childA と grandchildX の比較
103// childA (node1) は grandchildX (node2) を包含します。
104// grandchildX (node2) は childA (node1) に包含されます。
105echo describeNodePosition($childA, $grandchildX);
106echo "\n";
107
108// 例 5: grandchildX と childA の比較
109// childA (node2) は grandchildX (node1) を包含します。
110// grandchildX (node1) は childA (node2) に包含されます。
111echo describeNodePosition($grandchildX, $childA);
112echo "\n";
113
114// 例 6: childA と unattachedNode の比較
115// ノードは互いに接続されていません。
116echo describeNodePosition($childA, $unattachedNode);
117echo "\n";
118
119?>

このサンプルコードは、PHPのDOM拡張機能を用いて、WebページやXMLドキュメントの構造を表すDOMツリーにおける二つのノード（要素やテキストなど）の相対的な位置関係を調べる方法を示しています。特にDOMNode::DOCUMENT_POSITION_PRECEDINGという定数を活用し、比較対象のノードが基準ノードよりも物理的に前に位置するかどうかを判定します。

describeNodePosition関数は、比較の基準となる最初のノードを$node1、比較対象となる二番目のノードを$node2として、二つのDOMNodeオブジェクトを引数に受け取ります。この関数は、内部で$node1->compareDocumentPosition($node2)メソッドを呼び出します。このメソッドは、二つのノード間の関係を示すビットマスクという数値の組み合わせを返します。例えば、$node2が$node1よりもツリー上で物理的に前にあれば、戻り値のビットマスクにはDOMNode::DOCUMENT_POSITION_PRECEDINGが含まれることになります。

関数は、このビットマスクとDOMNode::DOCUMENT_POSITION_PRECEDINGをはじめとする様々な定数をビット論理AND演算子（&）で比較することで、両ノードが「前にあるか」「後ろにあるか」「包含しているか」「包含されているか」「接続されていないか」といった詳細な位置関係を判別します。そして、その結果を人間が読みやすい説明文として文字列で返します。実行例では、異なるノードの組み合わせに対してこの関数を適用し、それぞれの位置関係がどのように報告されるかを確認することで、DOMツリー内のノードの配置をプログラムで正確に把握する手法を学ぶことができます。