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

Copy
1<?php
2
3/**
4 * PHP 8の新しいDOM APIを使用して、XMLノード間の位置関係を比較するサンプル。
5 *
6 * この関数は、Dom\Node::compareDocumentPosition() メソッドと、
7 * Dom\Node::DOCUMENT_POSITION_DISCONNECTED および Dom\Node::DOCUMENT_POSITION_PRECEDING
8 * 定数を用いて、ノードの相対的な位置を判別する方法を示します。
9 *
10 * 注: ユーザーは「所属クラス: Dom\XMLDocument」と指定しましたが、
11 * これらの位置関係を示す定数は、実際にはDom\Nodeクラスに定義されています。
12 * Dom\XMLDocumentは、Dom\Nodeを継承したドキュメントクラスであり、そのノードを扱う際にこれらの定数が活用されます。
13 */
14function demonstrateDomNodePositionComparison(): void
15{
16    // 1. 新しいXMLドキュメントを作成します。PHP 8では、Dom\XMLDocumentを使用します。
17    $document = new Dom\XMLDocument();
18    
19    // ルート要素を作成し、ドキュメントツリーに追加します。
20    $root = $document->createElement('root');
21    $document->appendChild($root);
22
23    // 子要素を2つ作成し、ルート要素に追加します。
24    // これらのノードはドキュメントツリーに接続されています。
25    $child1 = $document->createElement('child1');
26    $root->appendChild($child1);
27
28    $child2 = $document->createElement('child2');
29    $root->appendChild($child2);
30
31    // ドキュメントツリーに接続されていないノードを作成します。
32    // Dom\Elementを直接インスタンス化すると、ownerDocumentはnullとなり、
33    // ドキュメントツリーに属さない「切断された」状態になります。
34    $disconnectedNode = new Dom\Element('disconnectedNode');
35
36    echo "--- Dom\\Node::compareDocumentPosition() の使用例 ---" . PHP_EOL . PHP_EOL;
37
38    // --- 例1: 兄弟ノード間の位置関係 ---
39    // 'child1' と 'child2' を比較します。
40    // 'child1' はドキュメントツリー上で 'child2' より前に現れるため、
41    // 結果には Dom\Node::DOCUMENT_POSITION_PRECEDING 定数が含まれます。
42    $position1 = $child1->compareDocumentPosition($child2);
43    echo "1. 'child1' と 'child2' の位置関係:" . PHP_EOL;
44    if ($position1 & Dom\Node::DOCUMENT_POSITION_PRECEDING) {
45        echo "   - 'child1' は 'child2' の前に位置します (Dom\\Node::DOCUMENT_POSITION_PRECEDING)。" . PHP_EOL;
46    }
47    echo PHP_EOL;
48
49    // --- 例2: 逆の兄弟ノード間の位置関係 ---
50    // 'child2' と 'child1' を比較します。
51    // 'child2' はドキュメントツリー上で 'child1' より後に現れるため、
52    // 結果には Dom\Node::DOCUMENT_POSITION_FOLLOWING 定数が含まれます。
53    $position2 = $child2->compareDocumentPosition($child1);
54    echo "2. 'child2' と 'child1' の位置関係:" . PHP_EOL;
55    if ($position2 & Dom\Node::DOCUMENT_POSITION_FOLLOWING) {
56        echo "   - 'child2' は 'child1' の後に位置します (Dom\\Node::DOCUMENT_POSITION_FOLLOWING)。" . PHP_EOL;
57    }
58    echo PHP_EOL;
59
60    // --- 例3: 接続されていないノードとの位置関係 ---
61    // 'disconnectedNode' と 'child1' を比較します。
62    // 'disconnectedNode' はどのドキュメントツリーにも属していないため、
63    // 結果には Dom\Node::DOCUMENT_POSITION_DISCONNECTED 定数が含まれます。
64    $position3 = $disconnectedNode->compareDocumentPosition($child1);
65    echo "3. 'disconnectedNode' と 'child1' の位置関係:" . PHP_EOL;
66    if ($position3 & Dom\Node::DOCUMENT_POSITION_DISCONNECTED) {
67        echo "   - 'disconnectedNode' は 'child1' と切断されています (Dom\\Node::DOCUMENT_POSITION_DISCONNECTED)。" . PHP_EOL;
68    }
69    echo PHP_EOL;
70
71    // --- 例4: ドキュメントツリーからノードを取り外した場合 ---
72    // 'child1' をドキュメントツリーから取り外します。
73    $removedChild = $root->removeChild($child1);
74
75    // 取り外された 'child1' と、まだ接続されている 'child2' を比較します。
76    // 'removedChild' (元の'child1') はドキュメントツリーに接続されていないため、
77    // 結果には Dom\Node::DOCUMENT_POSITION_DISCONNECTED 定数が含まれます。
78    $position4 = $removedChild->compareDocumentPosition($child2);
79    echo "4. ドキュメントから取り外された 'child1' と 'child2' の位置関係:" . PHP_EOL;
80    if ($position4 & Dom\Node::DOCUMENT_POSITION_DISCONNECTED) {
81        echo "   - 取り外された 'child1' は 'child2' と切断されています (Dom\\Node::DOCUMENT_POSITION_DISCONNECTED)。" . PHP_EOL;
82    }
83    echo PHP_EOL;
84}
85
86// 関数を実行して、ノードの位置関係の比較デモンストレーションを開始します。
87demonstrateDomNodePositionComparison();

本サンプルコードは、PHP 8の新しいDOM APIを使用して、XMLドキュメント内のノードが互いにどのような位置関係にあるかを比較する方法を解説しています。

主要なメソッドとして、Dom\Node::compareDocumentPosition()があります。このメソッドは、比較対象のノードが基準となるノードに対して、ドキュメントツリー上でどのような位置関係にあるかを数値（ビットマスク）で返します。引数はなく、戻り値は整数値（int）です。

特に、Dom\Node::DOCUMENT_POSITION_DISCONNECTED定数は、比較対象のノードがドキュメントツリーに接続されていない状態、または比較されるノード同士が異なるドキュメントに属している場合に、compareDocumentPosition()の戻り値に含まれるビットです。また、Dom\Node::DOCUMENT_POSITION_PRECEDING定数は、比較対象のノードが基準となるノードよりもドキュメントツリー上で前に現れる場合に、戻り値に含まれます。

サンプルコードでは、Dom\XMLDocumentでXML構造を作成し、接続されたノードや意図的にドキュメントツリーから切り離したノードを比較することで、これらの定数がどのように利用されるかを示しています。なお、リファレンス情報ではDom\XMLDocumentに定数が所属するとありましたが、これらの位置関係を示す定数は実際にはDom\Nodeクラスに定義されており、Dom\XMLDocumentがDom\Nodeを継承しているためそのコンテキストで活用されます。

Copy
1<?php
2
3// PHPのDOM拡張を使用し、XMLノード間の位置関係（disposition）を比較します。
4// 特に、DOMNode::DOCUMENT_POSITION_DISCONNECTED 定数の意味を実演します。
5
6/**
7 * 2つのDOMノード間の位置関係を比較し、
8 * DOMNode::DOCUMENT_POSITION_DISCONNECTED 定数の動作を示すサンプル関数。
9 *
10 * この定数は、PHPのDOM拡張におけるノードの「配置関係（disposition）」を判断する際に使用され、
11 * 比較対象のノードが互いに異なるドキュメントに属しているか、
12 * あるいは同じドキュメントでもツリー上で接続されていない関係（祖先、子孫、先行者、後続者ではない）
13 * である場合に、DOMNode::compareDocumentPosition() メソッドの結果として設定されます。
14 */
15function demonstrateDocumentPositionDisconnected(): void
16{
17    echo "--- DOMノードの位置関係の比較と DOCUMENT_POSITION_DISCONNECTED の確認 ---\n\n";
18
19    // 1. 最初のDOMドキュメントを作成し、XML文字列を読み込む
20    $doc1 = new DOMDocument('1.0', 'UTF-8');
21    $doc1->loadXML('<root><item id="itemA">Item A</item><item id="itemB">Item B</item></root>');
22
23    // doc1からノードAとノードBを取得
24    // getElementById は DTDやXSDがないと動作しない場合があるため、getElementsByTagNameで取得します。
25    $nodeA = $doc1->getElementsByTagName('item')->item(0); // <item id="itemA">
26    $nodeB = $doc1->getElementsByTagName('item')->item(1); // <item id="itemB">
27
28    // 2. 異なるDOMドキュメントを作成し、XML文字列を読み込む
29    $doc2 = new DOMDocument('1.0', 'UTF-8');
30    $doc2->loadXML('<other><element>Other Content</element></other>');
31    // doc2からノードCを取得
32    $nodeC = $doc2->getElementsByTagName('element')->item(0);
33
34    // 3. どのドキュメントにもまだ追加されていない新しいノードを作成
35    $orphanNode = new DOMElement('orphan');
36    $orphanNode->textContent = 'I am an orphan node.';
37
38    echo "--- ケース1: 同じドキュメント内の接続されたノードの比較 ---\n";
39    echo "  ノードA (doc1) と ノードB (doc1, 兄弟関係)\n";
40    if ($nodeA && $nodeB) {
41        // ノードAとノードBは同じドキュメントに属し、兄弟関係にあるため接続されています。
42        // compareDocumentPositionはノード間の相対的な位置を示すビットマスクを返します。
43        $position = $nodeA->compareDocumentPosition($nodeB);
44
45        // DOCUMENT_POSITION_DISCONNECTED フラグが設定されているか確認
46        if ($position & DOMNode::DOCUMENT_POSITION_DISCONNECTED) {
47            echo "  結果: ノードAとノードBは DISCONNECTED です。\n";
48        } else {
49            echo "  結果: ノードAとノードBは DISCONNECTED ではありません。(期待通り)\n";
50        }
51        // 参考情報として、他の関連フラグも表示できます。
52        if ($position & DOMNode::DOCUMENT_POSITION_FOLLOWING) {
53            echo "  補足: ノードBはノードAの後にあります。\n";
54        }
55    } else {
56        echo "  エラー: ノードAまたはノードBが見つかりません。\n";
57    }
58    echo "\n";
59
60    echo "--- ケース2: 異なるドキュメントのノードの比較 ---\n";
61    echo "  ノードA (doc1) と ノードC (doc2)\n";
62    if ($nodeA && $nodeC) {
63        // ノードAとノードCは異なるDOMドキュメントに属するため、DISCONNECTEDです。
64        $position = $nodeA->compareDocumentPosition($nodeC);
65
66        if ($position & DOMNode::DOCUMENT_POSITION_DISCONNECTED) {
67            echo "  結果: ノードAとノードCは DISCONNECTED です。(期待通り)\n";
68        } else {
69            echo "  結果: ノードAとノードCは DISCONNECTED ではありません。\n";
70        }
71    } else {
72        echo "  エラー: ノードAまたはノードCが見つかりません。\n";
73    }
74    echo "\n";
75
76    echo "--- ケース3: ドキュメントに属していないノードとの比較 ---\n";
77    echo "  ノードA (doc1) と 孤立ノード (どのドキュメントにも未追加)\n";
78    if ($nodeA && $orphanNode) {
79        // ノードAはdoc1に属していますが、orphanNodeはどのドキュメントにも属していないため、DISCONNECTEDです。
80        $position = $nodeA->compareDocumentPosition($orphanNode);
81
82        if ($position & DOMNode::DOCUMENT_POSITION_DISCONNECTED) {
83            echo "  結果: ノードAと孤立ノードは DISCONNECTED です。(期待通り)\n";
84        } else {
85            echo "  結果: ノードAと孤立ノードは DISCONNECTED ではありません。\n";
86        }
87    } else {
88        echo "  エラー: ノードAまたは孤立ノードが見つかりません。\n";
89    }
90    echo "\n";
91}
92
93// サンプル関数を実行
94demonstrateDocumentPositionDisconnected();
95

PHPのDOM拡張で提供されるDOCUMENT_POSITION_DISCONNECTED定数は、XMLノード間の位置関係を比較する際に用いられる整数値です。この定数自体に引数はなく、その値は整数型（int）です。主にDOMNode::compareDocumentPosition()メソッドの戻り値として使用され、比較対象のノードが互いに異なるドキュメントに属している場合や、同じドキュメント内でもツリー上で接続されていない関係（祖先、子孫、先行者、後続者ではない）にある場合に、そのメソッドの結果がこの定数を含むビットマスクとして返されます。

サンプルコードでは、この定数の動作を三つのケースで実演しています。まず、同じDOMドキュメント内の兄弟ノード同士を比較すると、これらは接続されているためDOCUMENT_POSITION_DISCONNECTEDは設定されません。次に、全く異なるDOMドキュメントに属するノード同士を比較すると、これらは当然接続されていないため、この定数が設定されることを確認できます。最後に、どのドキュメントにもまだ追加されていない「孤立ノード」と既存ドキュメントのノードを比較した場合も、同様に接続されていないため、DOCUMENT_POSITION_DISCONNECTEDが設定されることを示しています。このように、この定数はノードが互いに「切り離された」関係にあるかどうかを正確に判断するために役立ちます。