【PHP8.x】DOMElement::DOCUMENT_POSITION_DISCONNECTED定数の使い方

Copy
1<?php
2
3/**
4 * DOMノード間の位置関係を比較し、DOMNode::DOCUMENT_POSITION_* 定数の動作を示す関数です。
5 * DOMツリーにおけるノードの相対的な位置を理解するためのサンプルコードです。
6 */
7function demonstrateDomNodePositionComparison(): void
8{
9    // 1. 新しいDOMドキュメントを作成します。
10    // HTMLやXMLのような文書構造をプログラムで扱うための基本です。
11    $document = new DOMDocument();
12    $document->formatOutput = true; // 出力されたXML/HTMLを見やすく整形します。
13
14    // 2. ドキュメントのルート要素として 'root' 要素を作成し、追加します。
15    $root = $document->createElement('root');
16    $document->appendChild($root);
17
18    // 3. 'root' の子要素として 'childA' を作成し、追加します。
19    $childA = $document->createElement('childA', 'これは最初の要素です。');
20    $root->appendChild($childA);
21
22    // 4. 'root' の子要素として 'childB' を作成し、追加します。
23    // このノードは 'childA' の後にドキュメントツリーに配置されます。
24    $childB = $document->createElement('childB', 'これは次の要素です。');
25    $root->appendChild($childB);
26
27    // 5. まだドキュメントツリーに追加されていない、孤立した要素 'disconnectedNode' を作成します。
28    // このノードはどの親ノードにも属していません。
29    $disconnectedNode = $document->createElement('disconnectedNode', 'これはツリー外の要素です。');
30
31    echo "--- DOMノード位置比較のデモンストレーション ---\n";
32    echo "比較対象ノード: childA, childB, disconnectedNode\n\n";
33
34    // --- ケース1: ノードが別のノードの前に位置する場合 (DOMNode::DOCUMENT_POSITION_PRECEDING) ---
35    // 'childB' から見て 'childA' はその前に存在します。
36    echo "■ ケース1: 'childB' と 'childA' の比較\n";
37    echo "  'childB' は 'childA' の後に位置しています。\n";
38    $positionResult1 = $childB->compareDocumentPosition($childA);
39
40    // DOCUMENT_POSITION_PRECEDING は、比較対象ノードが呼び出し元ノードより前に位置することを示します。
41    // compareDocumentPosition メソッドはビットマスクを返すため、ビットAND演算子 (&) を使って
42    // 特定のフラグが立っているか (その状態であるか) をチェックします。
43    if ($positionResult1 & DOMNode::DOCUMENT_POSITION_PRECEDING) {
44        echo "  結果: 'childA' は 'childB' の前にあります。(DOMNode::DOCUMENT_POSITION_PRECEDING)\n";
45    } else {
46        echo "  結果: 'childA' は 'childB' の前にありません。\n";
47    }
48    echo "\n";
49
50    // --- ケース2: ノードが互いに接続されていない場合 (DOMNode::DOCUMENT_POSITION_DISCONNECTED) ---
51    // 'disconnectedNode' はドキュメントツリーに追加されていないため、他のノードとは切断されています。
52    echo "■ ケース2: 'childA' と 'disconnectedNode' の比較\n";
53    echo "  'disconnectedNode' はドキュメントツリーに追加されていません。\n";
54    $positionResult2 = $childA->compareDocumentPosition($disconnectedNode);
55
56    // DOCUMENT_POSITION_DISCONNECTED は、2つのノードが同じドキュメント内に存在しても、
57    // ツリー内で直接的な親子関係や兄弟関係になく、切断されている状態を示します。
58    // (例: 一方がまだドキュメントツリーに追加されていない、あるいは完全に異なるサブツリーにある)
59    if ($positionResult2 & DOMNode::DOCUMENT_POSITION_DISCONNECTED) {
60        echo "  結果: 'childA' と 'disconnectedNode' は切断されています。(DOMNode::DOCUMENT_POSITION_DISCONNECTED)\n";
61    } else {
62        echo "  結果: 'childA' と 'disconnectedNode' は接続されています。\n";
63    }
64    echo "\n";
65
66    // --- ケース3: ノードが自分自身と比較される場合 ---
67    echo "■ ケース3: 'childA' と 'childA' の比較\n";
68    $positionResult3 = $childA->compareDocumentPosition($childA);
69
70    // ノードを自分自身と比較した場合の結果は 0 となり、どの位置関係フラグも設定されません。
71    if ($positionResult3 === 0) {
72        echo "  結果: 'childA' は自分自身と比較され、同じノードとして認識されました。(結果は0)\n";
73    } else {
74        echo "  結果: 'childA' は自分自身と比較されましたが、予期せぬ結果です。(結果: " . $positionResult3 . ")\n";
75    }
76    echo "\n";
77
78    echo "--- デモンストレーション終了 ---\n";
79}
80
81// 上記のデモンストレーション関数を実行します。
82demonstrateDomNodePositionComparison();
83

PHP 8におけるDOMNode::DOCUMENT_POSITION_DISCONNECTED定数は、DOMノード間の位置関係を示す整数値の一つです。この定数自体に引数はなく、常に特定の整数値を持ち、主にDOMNode::compareDocumentPositionメソッドの戻り値を解釈する際に利用されます。compareDocumentPositionメソッドは、引数として比較したい別のDOMノードを受け取り、呼び出し元のノードと引数のノードがドキュメントツリー内でどのような位置関係にあるかを整数値のビットマスクとして返します。この戻り値はint型です。

サンプルコードでは、まず新しいDOMドキュメントを作成し、root、childA、childBといったノードを順にツリーに追加しています。一方で、disconnectedNodeは作成されるものの、意図的にドキュメントツリーには追加されず、どの親にも属さない「孤立した」状態にあります。

childBとchildAを比較するケースでは、compareDocumentPositionメソッドが返す結果にDOMNode::DOCUMENT_POSITION_PRECEDINGが含まれているかをビットAND演算子&で確認しています。これは、比較対象のchildAがchildBの「前に位置する」ことを示します。

特にDOMNode::DOCUMENT_POSITION_DISCONNECTEDの挙動を示すのは、childAとツリーに接続されていないdisconnectedNodeを比較するケースです。このとき、compareDocumentPositionの戻り値にDOMNode::DOCUMENT_POSITION_DISCONNECTEDが含まれていると判定され、2つのノードが同じドキュメント内に存在するものの、ツリー上での直接的な接続がない、つまり「切断された」状態であることが確認できます。このように、この定数はノードがドキュメントツリーに属しているか、あるいは比較対象のノードと構造的に関連があるかを判断するのに役立ちます。

Copy
1<?php
2
3/**
4 * DOMノードの位置関係を比較し、DOCUMENT_POSITION_DISCONNECTEDの状態を理解するサンプルコード。
5 *
6 * DOCUMENT_POSITION_DISCONNECTED は、2つのノードが同じドキュメントに属しているが、
7 * ドキュメントツリー内で接続されていない（例: 一方が孤立ノードである）状態を示します。
8 * これはDOMNode::compareDocumentPosition()メソッドの戻り値の一部として使用されます。
9 */
10function compareDomNodePositions(): void
11{
12    // 1. 新しいDOMドキュメントを作成します。
13    $dom = new DOMDocument('1.0', 'UTF-8');
14    $dom->formatOutput = true; // 出力を見やすくするため
15
16    // 2. ルート要素を作成し、ドキュメントに追加します。
17    $rootElement = $dom->createElement('root');
18    $dom->appendChild($rootElement);
19
20    // 3. 最初のDOM要素（ノードA）を作成し、ルート要素の子としてドキュメントツリーに追加します。
21    $nodeA = $dom->createElement('elementA', 'Hello');
22    $rootElement->appendChild($nodeA);
23
24    // 4. 2番目のDOM要素（ノードB）を作成します。
25    //    このノードはまだドキュメントツリーに追加されていません（孤立ノードです）。
26    $nodeB = $dom->createElement('elementB', 'World');
27
28    // 5. 3番目のDOM要素（ノードC）を作成します。
29    //    このノードもドキュメントツリーには追加しません。
30    $nodeC = $dom->createElement('elementC', 'Another Disconnected');
31
32    // 6. 4番目のDOM要素（ノードD）を作成し、ルート要素の子として追加します。
33    //    これはノードAと同じ親を持つ兄弟ノードです。
34    $nodeD = $dom->createElement('elementD', 'Another Child');
35    $rootElement->appendChild($nodeD);
36
37
38    echo "--- DOMノードの位置関係比較シナリオ ---\n";
39
40    // シナリオ1: 接続されているノードと、同じドキュメント内の孤立ノードの比較
41    // ノードAはDOMツリー内、ノードBは孤立しています。
42    echo "\nシナリオ1: 接続されているノードA と 孤立ノードB の比較\n";
43    $positionAB = $nodeA->compareDocumentPosition($nodeB);
44
45    // DOMNode::DOCUMENT_POSITION_DISCONNECTED 定数が結果に含まれているかを確認します。
46    // ビットAND演算子 (&) を使用して、特定のビットが設定されているかをチェックします。
47    if (($positionAB & DOMNode::DOCUMENT_POSITION_DISCONNECTED) === DOMNode::DOCUMENT_POSITION_DISCONNECTED) {
48        echo "  結果: ノードAとノードBはツリー内で接続されていません (DOCUMENT_POSITION_DISCONNECTED)。\n";
49    } else {
50        echo "  結果: ノードAとノードBはツリー内で接続されています。\n";
51    }
52    echo "  実際の比較結果 (ビットマスク): " . $positionAB . "\n";
53    // 補足: 通常、DISCONNECTEDと同時にFOLLOWINGやPRECEDINGもセットされることがあります。
54    // これは、ノードBがノードAの後に来ることを文書順序で示唆します。
55    if (($positionAB & DOMNode::DOCUMENT_POSITION_FOLLOWING) === DOMNode::DOCUMENT_POSITION_FOLLOWING) {
56        echo "  補足: ノードBはノードAの後に位置しています (文書順序)。\n";
57    }
58
59
60    // シナリオ2: 同じドキュメント内の、孤立ノード同士の比較
61    // ノードBとノードCはどちらもDOMツリーに追加されていません。
62    echo "\nシナリオ2: 孤立ノードB と 孤立ノードC の比較\n";
63    $positionBC = $nodeB->compareDocumentPosition($nodeC);
64
65    if (($positionBC & DOMNode::DOCUMENT_POSITION_DISCONNECTED) === DOMNode::DOCUMENT_POSITION_DISCONNECTED) {
66        echo "  結果: ノードBとノードCはツリー内で接続されていません (DOCUMENT_POSITION_DISCONNECTED)。\n";
67    } else {
68        echo "  結果: ノードBとノードCはツリー内で接続されています。\n";
69    }
70    echo "  実際の比較結果 (ビットマスク): " . $positionBC . "\n";
71    if (($positionBC & DOMNode::DOCUMENT_POSITION_FOLLOWING) === DOMNode::DOCUMENT_POSITION_FOLLOWING) {
72        echo "  補足: ノードCはノードBの後に位置しています (文書順序)。\n";
73    }
74
75
76    // シナリオ3: 接続されているが、直接の親子関係がないノード同士の比較 (同じ親を持つ兄弟ノード)
77    // ノードAとノードDは両方ともルート要素の子であり、同じドキュメントツリーに接続されています。
78    echo "\nシナリオ3: 接続されているノードA と ノードD の比較\n";
79    $positionAD = $nodeA->compareDocumentPosition($nodeD);
80
81    if (($positionAD & DOMNode::DOCUMENT_POSITION_DISCONNECTED) === DOMNode::DOCUMENT_POSITION_DISCONNECTED) {
82        echo "  結果: ノードAとノードDはツリー内で接続されていません (DOCUMENT_POSITION_DISCONNECTED)。\n";
83    } else {
84        echo "  結果: ノードAとノードDはツリー内で接続されています。\n";
85    }
86    echo "  実際の比較結果 (ビットマスク): " . $positionAD . "\n";
87    if (($positionAD & DOMNode::DOCUMENT_POSITION_FOLLOWING) === DOMNode::DOCUMENT_POSITION_FOLLOWING) {
88        echo "  補足: ノードDはノードAの後に位置しています (文書順序)。\n";
89    }
90
91
92    // シナリオ4: 同じノード同士の比較
93    // ノードAとノードAを比較します。この場合はDOCUMENT_POSITION_SAME_NODEになるはずです。
94    echo "\nシナリオ4: 同じノードA と ノードA の比較\n";
95    $positionAA = $nodeA->compareDocumentPosition($nodeA);
96
97    if (($positionAA & DOMNode::DOCUMENT_POSITION_DISCONNECTED) === DOMNode::DOCUMENT_POSITION_DISCONNECTED) {
98        echo "  結果: ノードAとノードAはツリー内で接続されていません (DOCUMENT_POSITION_DISCONNECTED)。\n";
99    } else {
100        echo "  結果: ノードAとノードAはツリー内で接続されています。\n";
101    }
102    echo "  実際の比較結果 (ビットマスク): " . $positionAA . "\n";
103    if (($positionAA & DOMNode::DOCUMENT_POSITION_SAME_NODE) === DOMNode::DOCUMENT_POSITION_SAME_NODE) {
104        echo "  補足: 比較対象は同じノードです (DOCUMENT_POSITION_SAME_NODE)。\n";
105    }
106}
107
108// 上記で定義した比較関数を実行します。
109compareDomNodePositions();

PHP 8のDOMNode::DOCUMENT_POSITION_DISCONNECTED定数は、XMLやHTML文書のDOMツリーにおいて、二つのノードが「互いに接続されていない」状態を示す整数値です。この定数は、主にDOMNode::compareDocumentPosition()メソッドの戻り値を解釈する際に利用されます。compareDocumentPosition()は、比較対象の二つのDOMノード間の位置関係を整数値（ビットマスク）で返し、DOCUMENT_POSITION_DISCONNECTEDはその中に含まれる可能性のあるフラグの一つです。

具体的には、一方または両方のノードがまだドキュメントツリーに追加されていない「孤立ノード」である場合、この定数のビットが戻り値に設定されます。これにより、同じドキュメントに属していても、構造的に関連性がない状態を識別できます。サンプルコードでは、DOMDocumentを作成し、一部のノードをドキュメントツリーに追加せずに孤立させ、compareDocumentPosition()を使ってこれらのノードが「接続されていない」状態であることをビットAND演算子&で判定する様子を示しています。この定数自体に引数はなく、それ自体が整数値として定義されており、ノードがツリー内で適切に配置されているかを確認するのに役立ちます。