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

Copy
1<?php
2
3/**
4 * DOMノード間の位置を比較するサンプル関数。
5 * システムエンジニアを目指す初心者向けに、DOMツリーにおけるノードの相対的な位置関係を
6 * どのように判断するかを Dom\CharacterData の定数を使って示します。
7 */
8function demonstrateNodePositionComparison(): void
9{
10    // 1. 新しいDOMドキュメントを作成
11    $dom = new DOMDocument('1.0', 'UTF-8');
12    // 出力時に整形されるように設定（デバッグや可読性向上に役立つ）
13    $dom->formatOutput = true; 
14
15    // 2. ドキュメントにルート要素を追加
16    $root = $dom->createElement('root');
17    $dom->appendChild($root);
18
19    // 3. 複数のテキストノード（Dom\CharacterData を継承）を作成し、ルート要素に追加
20    // これらのノードは、DOMツリー内での位置関係を比較するために使用されます。
21    
22    // ノードA: 最初のテキストノード
23    $nodeA = $dom->createTextNode('Node A: Hello ');
24    $root->appendChild($nodeA);
25
26    // ノードB: 2番目のテキストノード
27    $nodeB = $dom->createTextNode('Node B: World');
28    $root->appendChild($nodeB);
29
30    // 4. ノード間の相対的な位置を比較する
31    echo "--- ノードA と ノードB の位置比較 ---\n";
32
33    // nodeA から見て nodeB の位置を比較します。
34    // compareDocumentPosition() メソッドは、呼び出し元のノード（$nodeA）から見て
35    // 引数で指定されたノード（$nodeB）がどこにあるかを示すビットマスク値を返します。
36    $positionAB = $nodeA->compareDocumentPosition($nodeB);
37    echo "ノードAから見たノードBの位置:\n";
38    // Dom\CharacterData::DOCUMENT_POSITION_FOLLOWING は、比較対象のノードが
39    // 呼び出し元のノードの後に続くことを示します。
40    if (($positionAB & Dom\CharacterData::DOCUMENT_POSITION_FOLLOWING) === Dom\CharacterData::DOCUMENT_POSITION_FOLLOWING) {
41        echo "- ノードBはノードAの後に続きます。\n";
42    }
43
44    // nodeB から見て nodeA の位置を比較します。
45    $positionBA = $nodeB->compareDocumentPosition($nodeA);
46    echo "ノードBから見たノードAの位置:\n";
47    // Dom\CharacterData::DOCUMENT_POSITION_PRECEDING は、比較対象のノードが
48    // 呼び出し元のノードの前に先行することを示します。
49    if (($positionBA & Dom\CharacterData::DOCUMENT_POSITION_PRECEDING) === Dom\CharacterData::DOCUMENT_POSITION_PRECEDING) {
50        echo "- ノードAはノードBの前に先行します。\n";
51    }
52
53    // 5. その他の位置関係の比較例
54    echo "\n--- その他の位置関係の比較 ---\n";
55
56    // ドキュメントツリーに属していないノードを作成
57    $disconnectedNode = $dom->createTextNode('Disconnected Node');
58    
59    // nodeA とツリーに属していないノードを比較
60    $positionDisconnected = $nodeA->compareDocumentPosition($disconnectedNode);
61    echo "ノードAから見た切断されたノードの位置:\n";
62    // Dom\CharacterData::DOCUMENT_POSITION_DISCONNECTED は、ノードが同じドキュメントに
63    // 属していないか、ドキュメントツリーの同じ部分に属していないことを示します。
64    if (($positionDisconnected & Dom\CharacterData::DOCUMENT_POSITION_DISCONNECTED) === Dom\CharacterData::DOCUMENT_POSITION_DISCONNECTED) {
65        echo "- ノードはドキュメントツリーから切断されています。\n";
66    }
67
68    // 自分自身との比較
69    $positionSelf = $nodeA->compareDocumentPosition($nodeA);
70    echo "ノードAから見たノードAの位置:\n";
71    // 同じノードを比較した場合、結果は 0 になります。
72    if ($positionSelf === 0) {
73        echo "- 同じノードです。\n";
74    }
75}
76
77// 関数を実行して、DOMノードの位置比較の動作を確認
78demonstrateNodePositionComparison();
79

このサンプルコードは、PHPのDOM操作において、複数のノード間の相対的な位置関係を判断する方法をDom\CharacterData::DOCUMENT_POSITION_FOLLOWING定数を用いて示しています。

Dom\CharacterData::DOCUMENT_POSITION_FOLLOWINGは、DOMツリー内で、あるノードが比較対象のノードの後に続く場合に、その位置関係を示すための定数です。この定数自体に引数はなく、直接の戻り値もありませんが、DOMNode::compareDocumentPosition()メソッドの戻り値（ビットマスク値）を評価する際に使用されます。compareDocumentPosition()メソッドは、呼び出し元のノードから見て引数で指定されたノードがどの位置にあるかを示す数値を返します。

サンプルコードでは、まず二つのテキストノード $nodeA と $nodeB を作成し、DOMツリーに追加しています。$nodeA->compareDocumentPosition($nodeB)の結果がDOCUMENT_POSITION_FOLLOWINGを含む場合、$nodeBが$nodeAの後に位置することが判断できます。逆に、$nodeBから$nodeAを比較する際には、DOCUMENT_POSITION_PRECEDINGという定数を使用して、$nodeAが$nodeBの前に先行することを示しています。これにより、DOMツリー内でのノードの順序を正確に把握することが可能になります。

Copy
1<?php
2
3// PHP 8以降の新しいDOM名前空間を使用します。
4use Dom\Document;
5use Dom\Node;
6
7/**
8 * 2つのDOMノードの相対的な位置を比較し、
9 * 最初のノードが2番目のノードの後に続くかどうかを判定します。
10 *
11 * この関数は、Dom\Node::compareDocumentPosition() メソッドを使用し、
12 * その戻り値を Dom\CharacterData::DOCUMENT_POSITION_FOLLOWING 定数と論理AND演算で比較します。
13 * Dom\CharacterData::DOCUMENT_POSITION_FOLLOWING は、
14 * 比較対象のノードが基準ノードのDOMツリー上の「後に位置する」ことを示すビットフラグです。
15 * つまり、$node1 が $node2 のDOMツリー上で物理的に後に位置する場合にこのフラグがセットされます。
16 *
17 * @param Node $node1 比較の基準となるノード。
18 * @param Node $node2 $node1と比較されるノード。
19 * @return bool $node1が$node2の後に続く場合にtrue、そうでない場合はfalseを返します。
20 */
21function checkNodePositionFollowing(Node $node1, Node $node2): bool
22{
23    // compareDocumentPosition() メソッドは、2つのノードの相対的な位置をビットマスクで返します。
24    // DOCUMENT_POSITION_FOLLOWING は、基準ノード ($node1) が比較対象ノード ($node2) の後に来ることを示すビットです。
25    $position = $node1->compareDocumentPosition($node2);
26
27    // ビット論理AND演算子 (`&`) を使って、
28    // 返された $position に DOCUMENT_POSITION_FOLLOWING フラグ (ビット) が立っているかを確認します。
29    // フラグが立っていれば ($position & Dom\CharacterData::DOCUMENT_POSITION_FOLLOWING) の結果は非ゼロとなり、
30    // booleanにキャストすると true になります。
31    $isFollowing = (bool)($position & Dom\CharacterData::DOCUMENT_POSITION_FOLLOWING);
32
33    echo "  - ノード '" . $node1->nodeName . "' が ノード '" . $node2->nodeName . "' の後に続くか: " . ($isFollowing ? 'はい' : 'いいえ') . "\n";
34
35    return $isFollowing;
36}
37
38// --- サンプルコードの実行 ---
39
40// 新しいDOMドキュメントを作成
41$dom = new Document();
42$root = $dom->createElement('root');
43$dom->appendChild($root);
44
45// 要素とテキストノードを作成し、DOMツリーを構築
46$elementA = $dom->createElement('elementA');
47$textNodeA = $dom->createTextNode('テキストA'); // Dom\TextはDom\CharacterDataの子クラスです
48$root->appendChild($elementA);
49$elementA->appendChild($textNodeA);
50
51$elementB = $dom->createElement('elementB');
52$textNodeB = $dom->createTextNode('テキストB'); // Dom\TextはDom\CharacterDataの子クラスです
53$root->appendChild($elementB);
54$elementB->appendChild($textNodeB);
55
56// ここでのDOMツリーの論理的な順序（rootの子として）：
57// root
58//  ├─ elementA
59//  │  └─ textNodeA
60//  └─ elementB
61//     └─ textNodeB
62
63echo "DOMノードの位置関係の比較:\n";
64
65echo "\n--- 比較1: \$textNodeB と \$textNodeA --- (期待値: true)\n";
66// textNodeB は DOMツリー上で textNodeA の後に位置します。
67checkNodePositionFollowing($textNodeB, $textNodeA);
68
69echo "\n--- 比較2: \$textNodeA と \$textNodeB --- (期待値: false)\n";
70// textNodeA は DOMツリー上で textNodeB の前に位置します。
71checkNodePositionFollowing($textNodeA, $textNodeB);
72
73echo "\n--- 比較3: \$elementB と \$elementA --- (期待値: true)\n";
74// elementB は DOMツリー上で elementA の後に位置します。
75checkNodePositionFollowing($elementB, $elementA);
76
77echo "\n--- 比較4: \$elementA と \$elementB --- (期待値: false)\n";
78// elementA は DOMツリー上で elementB の前に位置します。
79checkNodePositionFollowing($elementA, $elementB);
80
81echo "\n--- 比較5: \$elementA と \$elementA --- (期待値: false)\n";
82// 同じノードを比較した場合 (DOCUMENT_POSITION_SAME_NODE が返されるため、DOCUMENT_POSITION_FOLLOWING はセットされません)。
83checkNodePositionFollowing($elementA, $elementA);
84

このPHPサンプルコードは、ウェブページの構造を表すDOMツリー上で、2つの要素がどちらが先に登場するかといった相対的な位置関係を判断する方法を示しています。具体的には、最初のノードが2番目のノードのDOMツリー上の後に物理的に位置するかどうかを判定します。

中心となるのは、Dom\Node::compareDocumentPosition()メソッドと、Dom\CharacterData::DOCUMENT_POSITION_FOLLOWING定数です。compareDocumentPosition()メソッドは、2つのノード間の位置関係を数値のビットフラグの組み合わせとして返します。この戻り値と、DOCUMENT_POSITION_FOLLOWING定数をビット論理AND演算子（&）で組み合わせることで、最初のノードが2番目のノードのDOMツリー上の後に位置するかどうかを確認できます。DOCUMENT_POSITION_FOLLOWINGは、比較対象のノードが基準ノードの「後に続く」ことを示す定数です。

checkNodePositionFollowing関数は、比較する2つのDom\Node型の引数$node1と$node2を受け取ります。この関数は、$node1が$node2の後に位置する場合にtrueを、そうでない場合はfalseをブール値として返します。例えば、DOMツリーで先に定義されたノードと後に定義されたノードを比較すると、後に続くノードを基準とした比較ではtrueが返されることがわかります。この機能は、DOM操作において要素の順序を厳密に制御したい場合に役立ちます。