【PHP8.x】Dom\Element::DOCUMENT_POSITION_DISCONNECTED定数の使い方

Copy
1<?php
2
3/**
4 * 2つのDOMノード間の位置関係を比較し、結果を出力する関数。
5 *
6 * この関数は DOMNode::compareDocumentPosition() メソッドを使用し、
7 * ノード間の相対位置を示す定数（DOMNode::DOCUMENT_POSITION_DISCONNECTED,
8 * DOMNode::DOCUMENT_POSITION_PRECEDINGなど）がどのように返されるかを示します。
9 *
10 * @param DOMNode $nodeA 比較の基準となるノード。
11 * @param DOMNode $nodeB 比較対象となるノード。
12 * @param string $labelA nodeA の説明ラベル。
13 * @param string $labelB nodeB の説明ラベル。
14 */
15function compareDomNodes(DOMNode $nodeA, DOMNode $nodeB, string $labelA, string $labelB): void
16{
17    // compareDocumentPosition は、2つのノード間の位置関係をビットマスクで返します。
18    // DOCUMENT_POSITION_DISCONNECTED (0x01): 2つのノードが同じツリー内にないか、まだツリーに接続されていない。
19    // DOCUMENT_POSITION_PRECEDING (0x02): nodeB が nodeA のドキュメント順序で前に現れる。
20    // DOCUMENT_POSITION_FOLLOWING (0x04): nodeB が nodeA のドキュメント順序で後に現れる。
21    // DOCUMENT_POSITION_CONTAINS (0x08): nodeA が nodeB を含んでいる。
22    // DOCUMENT_POSITION_CONTAINED_BY (0x10): nodeA が nodeB に含まれている。
23    // DOCUMENT_POSITION_SAME_NODE (0x20): nodeA と nodeB が同じノードである。
24    $position = $nodeA->compareDocumentPosition($nodeB);
25
26    echo "--- 比較: {$labelA} と {$labelB} ---\n";
27
28    // DOCUMENT_POSITION_DISCONNECTED の確認
29    // 2つのノードが同じDOMツリー内にないか、どちらかがまだツリーに接続されていない場合に設定されます。
30    if (($position & DOMNode::DOCUMENT_POSITION_DISCONNECTED) > 0) {
31        echo "- {$labelA} と {$labelB} は接続されていません (Disconnected).\n";
32    }
33
34    // DOCUMENT_POSITION_PRECEDING の確認
35    // 比較対象の $nodeB が基準の $nodeA よりもDOMツリーのドキュメント順序で前に現れる場合に設定されます。
36    if (($position & DOMNode::DOCUMENT_POSITION_PRECEDING) > 0) {
37        echo "- {$labelB} は {$labelA} より前にあります (Preceding).\n";
38    }
39
40    // DOCUMENT_POSITION_FOLLOWING の確認
41    // 比較対象の $nodeB が基準の $nodeA よりもDOMツリーのドキュメント順序で後に現れる場合に設定されます。
42    if (($position & DOMNode::DOCUMENT_POSITION_FOLLOWING) > 0) {
43        echo "- {$labelB} は {$labelA} より後にあります (Following).\n";
44    }
45
46    // DOCUMENT_POSITION_CONTAINS の確認
47    // 基準の $nodeA が比較対象の $nodeB を含んでいる場合に設定されます。
48    if (($position & DOMNode::DOCUMENT_POSITION_CONTAINS) > 0) {
49        echo "- {$labelA} が {$labelB} を含んでいます (Contains).\n";
50    }
51
52    // DOCUMENT_POSITION_CONTAINED_BY の確認
53    // 基準の $nodeA が比較対象の $nodeB に含まれている場合に設定されます。
54    if (($position & DOMNode::DOCUMENT_POSITION_CONTAINED_BY) > 0) {
55        echo "- {$labelA} が {$labelB} に含まれています (Contained By).\n";
56    }
57
58    // DOCUMENT_POSITION_SAME_NODE の確認
59    // $nodeA と $nodeB が同じノードである場合に設定されます。
60    if (($position & DOMNode::DOCUMENT_POSITION_SAME_NODE) > 0) {
61        echo "- {$labelA} と {$labelB} は同じノードです (Same Node).\n";
62    }
63    echo "\n";
64}
65
66// 1. 新しいDOMドキュメントを作成します。
67$document = new DOMDocument('1.0', 'UTF-8');
68$document->formatOutput = true; // 出力されるXMLを見やすくします
69
70// 2. ルート要素を作成し、ドキュメントに追加します。
71$rootElement = $document->createElement('root');
72$document->appendChild($rootElement);
73
74// 3. いくつかの要素を作成し、DOMツリーに追加してノード構造を構築します。
75$childElementA = $document->createElement('childA');
76$rootElement->appendChild($childElementA);
77
78$childElementB = $document->createElement('childB');
79$childElementA->appendChild($childElementB); // childB は childA の子ノードです
80
81$childElementC = $document->createElement('childC');
82$rootElement->appendChild($childElementC); // childC は root の子ノードで、childA の後に続きます
83
84// まだどのドキュメントにも追加されていない独立したノードを作成します。
85$isolatedElement = $document->createElement('isolated');
86
87echo "--- 構築されたDOM構造 ---\n";
88echo $document->saveXML();
89echo "\n";
90
91echo "--- ノード比較の実行結果 ---\n";
92
93// 比較例1: 同じドキュメント内のノードで、後の要素を比較 (DOCUMENT_POSITION_FOLLOWING の例)
94// childElementC はドキュメント順序で childElementA の後に現れます。
95compareDomNodes($childElementA, $childElementC, 'childA', 'childC');
96
97// 比較例2: 親ノードが子ノードを比較 (DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_CONTAINED_BY の例)
98// childElementA は childElementB を含んでいます。
99compareDomNodes($childElementA, $childElementB, 'childA', 'childB');
100
101// 比較例3: 子ノードが親ノードを比較 (DOCUMENT_POSITION_PRECEDING, DOCUMENT_POSITION_CONTAINED_BY の例)
102// childElementA はドキュメント順序で childElementB の前に現れ、
103// childElementB は childElementA に含まれています。
104compareDomNodes($childElementB, $childElementA, 'childB', 'childA');
105
106// 比較例4: 未接続ノードの比較 (DOMNode::DOCUMENT_POSITION_DISCONNECTED の例)
107// isolatedElement はまだドキュメントツリーに接続されていないため、rootElementとは接続されていません。
108compareDomNodes($rootElement, $isolatedElement, 'rootElement', 'isolatedElement');
109
110// 比較例5: 同じノード同士の比較 (DOMNode::DOCUMENT_POSITION_SAME_NODE の例)
111compareDomNodes($rootElement, $rootElement, 'rootElement', 'rootElement');

このサンプルコードは、PHPのDOM拡張機能におけるDOMNode::compareDocumentPosition()メソッドを利用し、二つのDOMノード間の位置関係を比較する方法を示しています。このメソッドは、基準となるノードと比較対象のノードの引数を受け取り、両者の相対的な位置を示すビットマスク形式の整数値を戻り値として返します。この戻り値は、複数の状態を同時に示すことができるため、ビットAND演算子（&）を使って特定の位置関係を判定します。

特に注目すべき定数として、DOMNode::DOCUMENT_POSITION_DISCONNECTEDがあります。これは、比較する二つのノードが同じドキュメントツリーに属していない場合や、どちらかがまだドキュメントに接続されていない場合に設定される状態を示します。また、キーワードであるDOMNode::DOCUMENT_POSITION_PRECEDINGは、比較対象のノードが基準のノードよりもドキュメントの順序で前に現れる場合に設定されます。他にも、ノードが後に現れるDOCUMENT_POSITION_FOLLOWING、基準ノードが比較対象ノードを含んでいるDOCUMENT_POSITION_CONTAINS、基準ノードが比較対象ノードに含まれているDOCUMENT_POSITION_CONTAINED_BY、そして二つのノードが全く同じであるDOCUMENT_POSITION_SAME_NODEといった定数があります。

サンプルコードでは、compareDomNodes関数がこれらの定数を使ってノード間の関係を詳細に判定し、その結果を出力しています。例えば、isolatedElementがまだドキュメントツリーに接続されていないことをDOCUMENT_POSITION_DISCONNECTEDで、childElementBがchildElementAに含まれていることをDOCUMENT_POSITION_CONTAINED_BYとDOCUMENT_POSITION_PRECEDINGの組み合わせで検出している様子が確認できます。

Copy
1<?php
2
3/**
4 * Dom\Node::DOCUMENT_POSITION_DISCONNECTED 定数の使用例を示す関数です。
5 *
6 * この定数は、DOM (Document Object Model) ノード間の位置関係を示すビットマスクの一部です。
7 * 特に、2つのノードが同じドキュメントツリーに属していない状態を示します。
8 * Dom\Element クラスは Dom\Node を継承しているため、そのインスタンスで
9 * compareDocumentPosition メソッドを呼び出し、この定数と比較できます。
10 */
11function demonstrateDomDisconnectedPosition(): void
12{
13    // 新しいDOMドキュメントを作成します。
14    $doc = new Dom\Document();
15
16    // ドキュメントに追加する予定の要素Aを作成します (この時点ではまだドキュメントツリーには属していません)。
17    $elementA = new Dom\Element('div');
18    $elementA->setAttribute('id', 'elementA');
19
20    // ドキュメントのルート要素として要素Bを作成し、ドキュメントに追加します。
21    $elementB = new Dom\Element('p');
22    $elementB->setAttribute('id', 'elementB');
23    $doc->appendChild($elementB); // $elementB は $doc の子ノードとなりました。
24
25    echo "--- Dom\\Node::DOCUMENT_POSITION_DISCONNECTED の使用例 ---\n\n";
26
27    echo "シナリオ1: 要素A (まだドキュメントに追加されていない) と 要素B (ドキュメントに追加済み) の比較\n";
28    // 要素Aと要素Bのドキュメント内での位置関係を比較します。
29    // compareDocumentPosition メソッドは、比較結果をビットマスクとして返します。
30    // Dom\Node::DOCUMENT_POSITION_DISCONNECTED は、ノードが同じドキュメントツリーに属していない場合に設定されるフラグです。
31    $position = $elementA->compareDocumentPosition($elementB);
32
33    echo "比較結果 (ビットマスク): " . $position . "\n";
34
35    // 比較結果に Dom\Node::DOCUMENT_POSITION_DISCONNECTED フラグが含まれているかチェックします。
36    if (($position & Dom\Node::DOCUMENT_POSITION_DISCONNECTED) === Dom\Node::DOCUMENT_POSITION_DISCONNECTED) {
37        echo "-> 結果: 要素Aと要素Bは、ドキュメントツリー内で互いに切断された位置にあります。\n";
38        echo "   (要素Aがまだどのドキュメントにも追加されていないため)\n";
39    } else {
40        echo "-> 結果: 要素Aと要素Bは、同じドキュメントツリー内で接続された位置にあります。\n";
41    }
42
43    echo "\n------------------------------------------------------\n";
44
45    echo "シナリオ2: 要素Aをドキュメントに追加後、再度比較\n";
46    // 要素Aをドキュメントに追加してみます。
47    $doc->appendChild($elementA); // $elementA も $doc の子ノードとなりました。
48
49    // 再度要素Aと要素Bの位置関係を比較します。
50    // 今度はどちらの要素も同じドキュメントツリー ($doc) 内に存在します。
51    $positionAfterAppend = $elementA->compareDocumentPosition($elementB);
52
53    echo "比較結果 (ビットマスク): " . $positionAfterAppend . "\n";
54
55    // 再び Dom\Node::DOCUMENT_POSITION_DISCONNECTED フラグが含まれているかチェックします。
56    if (($positionAfterAppend & Dom\Node::DOCUMENT_POSITION_DISCONNECTED) === Dom\Node::DOCUMENT_POSITION_DISCONNECTED) {
57        echo "-> 結果: 要素Aと要素Bは、ドキュメントツリー内で互いに切断された位置にあります。\n";
58    } else {
59        echo "-> 結果: 要素Aと要素Bは、同じドキュメントツリー内で接続された位置にあります。\n";
60        echo "   (要素Aもドキュメントに追加されたため、両者は同じツリー内にあります)\n";
61    }
62}
63
64// 上記の関数を実行し、動作を確認します。
65demonstrateDomDisconnectedPosition();

PHP 8のDom\Node::DOCUMENT_POSITION_DISCONNECTED定数は、DOM（Document Object Model）におけるノード間の位置関係を示すビットマスク定数の一つです。この定数は、二つのDOMノードが同じドキュメントツリーに属していない、つまり互いに「切断された」状態を識別するために使用されます。

サンプルコードでは、Dom\Elementクラスのインスタンスが持つcompareDocumentPositionメソッドと組み合わせて、ノードの接続状態を確認する方法を示しています。compareDocumentPositionメソッドは、比較対象のノード間の位置関係をビットマスクとして返します。この戻り値とDom\Node::DOCUMENT_POSITION_DISCONNECTED定数をビット論理積（&）で比較することで、特定のノードがドキュメントツリー内で切断された位置にあるかどうかを判別できます。

具体的な例として、まずドキュメントにまだ追加されていない要素Aと、すでに追加されている要素Bを比較します。この場合、両者は異なるツリー（要素Aはまだどのツリーにも属していない）と見なされるため、比較結果にDOCUMENT_POSITION_DISCONNECTEDのフラグが含まれます。次に、要素Aもドキュメントに追加した後、再度要素Aと要素Bを比較すると、両者は同じドキュメントツリー内に存在するため、今度は「切断されていない」と判定されることが示されています。この定数自体に引数はなく、特定の状況を示すための値として利用されます。