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

Copy
1<?php
2
3/**
4 * DOMノード間の位置関係を比較するサンプルコード。
5 *
6 * Dom\Node::compareDocumentPosition メソッドと関連定数 (例: Dom\Node::DOCUMENT_POSITION_PRECEDING,
7 * Dom\Node::DOCUMENT_POSITION_DISCONNECTED) の使用方法を示します。
8 * これらの定数は、主に Dom\Node クラスのインスタンスメソッドである compareDocumentPosition() の
9 * 戻り値と比較するために利用されます。
10 * リファレンス情報で「所属クラス: Dom\Document」とありますが、これは Dom\Document インスタンスが
11 * 関連するDOM操作で使用されることを意味し、定数自体は Dom\Node クラスで定義されています。
12 */
13function compareDomNodePositions(): void
14{
15    // 新しいDOMドキュメントを作成
16    $dom = new Dom\Document();
17    $dom->formatOutput = true; // XML出力の整形を有効にする
18
19    // ルート要素を作成し、ドキュメントに追加
20    $root = $dom->createElement('root');
21    $dom->appendChild($root);
22
23    // 子要素を作成
24    $child1 = $dom->createElement('child1');
25    $child2 = $dom->createElement('child2');
26    $grandchild = $dom->createElement('grandchild');
27
28    // DOMツリーを構築: root -> child1 -> grandchild, root -> child2
29    $root->appendChild($child1);
30    $child1->appendChild($grandchild);
31    $root->appendChild($child2); // child2 は child1 の後に来る兄弟ノード
32
33    echo "--- DOMノードの比較 ---" . PHP_EOL;
34    echo "現在のDOMツリーの構造:" . PHP_EOL;
35    echo $dom->saveXML() . PHP_EOL;
36
37    // ----------------------------------------------------
38    // 1. 同一ドキュメント内のノードの比較
39    //    キーワードに関連する DOCUMENT_POSITION_PRECEDING の例
40    // ----------------------------------------------------
41
42    // compareDocumentPosition($otherNode) メソッドは、$otherNode が
43    // メソッドを呼び出したノード (ここでは $this) に対してドキュメント内で
44    // どう位置するかを示すビットマスクを返します。
45
46    // 例1: $child2 から $child1 を比較
47    // $child1 は $child2 よりもドキュメントツリーの「前」に出現します。
48    // よって、比較結果は Dom\Node::DOCUMENT_POSITION_PRECEDING を含みます。
49    $result1 = $child2->compareDocumentPosition($child1);
50    echo "比較: \$child2->compareDocumentPosition(\$child1) (child1 は child2 より前)" . PHP_EOL;
51    if ($result1 & Dom\Node::DOCUMENT_POSITION_PRECEDING) {
52        echo "  - 結果: \$child1 は \$child2 の '前' に位置します (DOCUMENT_POSITION_PRECEDING)." . PHP_EOL;
53    }
54
55    // 例2: $child1 から $child2 を比較
56    // $child2 は $child1 よりもドキュメントツリーの「後」に出現します。
57    // よって、比較結果は Dom\Node::DOCUMENT_POSITION_FOLLOWING を含みます。
58    $result2 = $child1->compareDocumentPosition($child2);
59    echo "比較: \$child1->compareDocumentPosition(\$child2) (child2 は child1 より後)" . PHP_EOL;
60    if ($result2 & Dom\Node::DOCUMENT_POSITION_FOLLOWING) {
61        echo "  - 結果: \$child2 は \$child1 の '後' に位置します (DOCUMENT_POSITION_FOLLOWING)." . PHP_EOL;
62    }
63
64    // 例3: 親ノード ($child1) から子ノード ($grandchild) を比較
65    // $grandchild は $child1 によって「含まれて」います。
66    $result3 = $child1->compareDocumentPosition($grandchild);
67    echo "比較: \$child1->compareDocumentPosition(\$grandchild) (grandchild は child1 に含まれる)" . PHP_EOL;
68    if ($result3 & Dom\Node::DOCUMENT_POSITION_CONTAINS) {
69        echo "  - 結果: \$child1 は \$grandchild を '含んでいます' (DOCUMENT_POSITION_CONTAINS)." . PHP_EOL;
70    }
71
72
73    // ----------------------------------------------------
74    // 2. 異なるドキュメント、またはドキュメントに属さないノードの比較
75    //    DOCUMENT_POSITION_DISCONNECTED の例
76    // ----------------------------------------------------
77
78    // 新しいDOMドキュメントを作成し、それに属するノードを作成（元のドキュメントとは別）
79    $otherDom = new Dom\Document();
80    $otherNode = $otherDom->createElement('other');
81    $otherDom->appendChild($otherNode); // otherNode を新しいドキュメントに追加
82
83    // $child1 (元のドキュメント) と $otherNode (別のドキュメント) を比較
84    // これらは異なるドキュメントに属するため、「接続されていません」。
85    $result4 = $child1->compareDocumentPosition($otherNode);
86    echo "比較: \$child1->compareDocumentPosition(\$otherNode) (異なるドキュメントのノード)" . PHP_EOL;
87    if ($result4 & Dom\Node::DOCUMENT_POSITION_DISCONNECTED) {
88        echo "  - 結果: 両ノードは '接続されていません' (DOCUMENT_POSITION_DISCONNECTED)." . PHP_EOL;
89        echo "    (異なるDOMドキュメントに属しているため)" . PHP_EOL;
90    }
91
92    // ドキュメントに追加されていないノードを作成（同じドキュメントで作成したが、ツリーには未接続）
93    $floatingNode = $dom->createElement('floating'); 
94    // $root はドキュメントツリーに接続されていますが、$floatingNode はまだ接続されていません。
95    $result5 = $root->compareDocumentPosition($floatingNode);
96    echo "比較: \$root->compareDocumentPosition(\$floatingNode) (floatingNode は未接続)" . PHP_EOL;
97    if ($result5 & Dom\Node::DOCUMENT_POSITION_DISCONNECTED) {
98        echo "  - 結果: 両ノードは '接続されていません' (DOCUMENT_POSITION_DISCONNECTED)." . PHP_EOL;
99        echo "    (\$floatingNode がDOMドキュメントツリーに追加されていないため)" . PHP_EOL;
100    }
101}
102
103// 上で定義した関数を実行します
104compareDomNodePositions();

このサンプルコードは、PHPのDOM（Document Object Model）操作において、XMLやHTMLドキュメント内のノード（要素など）同士がどのように位置しているかを比較する方法を示しています。中心となるのはDom\Node::compareDocumentPosition()メソッドと、その結果を判断するための関連定数です。

Dom\Node::compareDocumentPosition()メソッドは、引数で渡された別のノードが、メソッドを呼び出したノードに対してドキュメントツリー内でどのような位置関係にあるかを数値（ビットマスク）で返します。この戻り値は複数の状態を示すことができるため、Dom\Node::DOCUMENT_POSITION_DISCONNECTEDやDom\Node::DOCUMENT_POSITION_PRECEDINGのような定数とビットAND演算子（&）を用いて、特定の位置関係であるかを判定します。

特にDom\Node::DOCUMENT_POSITION_DISCONNECTED定数は、比較している二つのノードが異なるDOMドキュメントツリーに属している場合や、どちらかのノードがまだドキュメントツリーに追加されていない「未接続」の状態であることを示します。一方、キーワードであるDom\Node::DOCUMENT_POSITION_PRECEDINGは、比較対象のノードが、メソッドを呼び出したノードよりもドキュメントツリーの読み込み順で「前」に位置していることを意味します。これらの定数自体には引数や戻り値はありませんが、compareDocumentPosition()メソッドの結果を解釈する上で不可欠な値として利用されます。

Copy
1<?php
2
3/**
4 * Dom\Node->compareDocumentPosition() メソッドを使用し、
5 * ノード間の位置関係、特に DOCUMENT_POSITION_DISCONNECTED 定数の意味を示すサンプルです。
6 *
7 * この定数は、比較対象のノードが同じドキュメントに所属していない（切断されている）場合に、
8 * compareDocumentPosition メソッドの戻り値に含まれるビットマスクの一つです。
9 *
10 * キーワード「disposition」を「ノードの配置状態」と解釈し、
11 * DOMドキュメント内でのノードの接続状態（disposition）を比較する例としています。
12 * システムエンジニアを目指す初心者が、DOMノード間の関係性を理解するのに役立ちます。
13 */
14function demonstrateDocumentPositionDisconnected(): void
15{
16    // 新しいDOMドキュメントを作成します。
17    $doc = new Dom\Document();
18    $doc->formatOutput = true; // 出力XMLを見やすくするための設定
19
20    // ルート要素を作成し、ドキュメントに追加します。
21    $root = $doc->createElement('root');
22    $doc->appendChild($root);
23
24    // ドキュメントに接続された子要素を作成し、ルート要素に追加します。
25    $connectedChild = $doc->createElement('connectedChild');
26    $root->appendChild($connectedChild);
27
28    // ドキュメントには追加されていない、独立した要素を作成します（これが「切断された」状態のノードです）。
29    $disconnectedElement = $doc->createElement('disconnectedElement');
30
31    echo "--- DOMノードの配置関係（Disposition）の比較 ---" . PHP_EOL;
32
33    // 1. 接続されたノードと、ドキュメントに追加されていない（切断された）ノードを比較します。
34    // $connectedChild は $doc に接続されていますが、$disconnectedElement はどのドキュメントにも所属していません。
35    // この比較では、Dom\Node::DOCUMENT_POSITION_DISCONNECTED フラグが戻り値に含まれるはずです。
36    $positionResult1 = $connectedChild->compareDocumentPosition($disconnectedElement);
37
38    echo PHP_EOL . "--- 比較 1: 接続されたノード と 切断されたノード ---" . PHP_EOL;
39    echo "  対象: 'connectedChild' (接続済み) と 'disconnectedElement' (未接続)" . PHP_EOL;
40    echo "  compareDocumentPosition の戻り値 (ビットマスク): " . $positionResult1 . PHP_EOL;
41
42    // 戻り値に Dom\Node::DOCUMENT_POSITION_DISCONNECTED フラグが含まれているかチェックします。
43    if (($positionResult1 & Dom\Node::DOCUMENT_POSITION_DISCONNECTED) === Dom\Node::DOCUMENT_POSITION_DISCONNECTED) {
44        echo "  結果: Dom\Node::DOCUMENT_POSITION_DISCONNECTED フラグが検出されました。" . PHP_EOL;
45        echo "        これは、両方のノードが同じドキュメントに接続されていないことを意味します。" . PHP_EOL;
46        echo "        ('disconnectedElement' はまだドキュメントツリーの一部ではありません)。" . PHP_EOL;
47    } else {
48        echo "  結果: Dom\Node::DOCUMENT_POSITION_DISCONNECTED フラグは検出されませんでした。" . PHP_EOL;
49    }
50
51    // 2. 同じドキュメントに接続されたノード同士を比較します。
52    // $connectedChild と $root はどちらも $doc に接続されています。
53    // この比較では、Dom\Node::DOCUMENT_POSITION_DISCONNECTED フラグは含まれないはずです。
54    $positionResult2 = $connectedChild->compareDocumentPosition($root);
55
56    echo PHP_EOL . "--- 比較 2: 同じドキュメント内の接続されたノード同士 ---" . PHP_EOL;
57    echo "  対象: 'connectedChild' (接続済み) と 'root' (接続済み)" . PHP_EOL;
58    echo "  compareDocumentPosition の戻り値 (ビットマスク): " . $positionResult2 . PHP_EOL;
59
60    // 戻り値に Dom\Node::DOCUMENT_POSITION_DISCONNECTED フラグが含まれているかチェックします。
61    if (($positionResult2 & Dom\Node::DOCUMENT_POSITION_DISCONNECTED) === Dom\Node::DOCUMENT_POSITION_DISCONNECTED) {
62        echo "  結果: Dom\Node::DOCUMENT_POSITION_DISCONNECTED フラグが検出されました。" . PHP_EOL;
63    } else {
64        echo "  結果: Dom\Node::DOCUMENT_POSITION_DISCONNECTED フラグは検出されませんでした。" . PHP_EOL;
65        echo "        これは、両方のノードが同じドキュメントに接続されていることを意味します。" . PHP_EOL;
66        // 他のビットマスク（例: CONTAINS や FOLLOWING）も含まれる可能性があります。
67        if (($positionResult2 & Dom\Node::DOCUMENT_POSITION_CONTAINS) === Dom\Node::DOCUMENT_POSITION_CONTAINS) {
68            echo "        さらに、'connectedChild' は 'root' 要素に含まれています（CONTAINS）。" . PHP_EOL;
69        }
70    }
71
72    echo PHP_EOL . "--- 現在のDOMドキュメントのXML構造 ---" . PHP_EOL;
73    echo $doc->saveXML();
74}
75
76// サンプル関数を実行します。
77demonstrateDocumentPositionDisconnected();

このPHPサンプルコードは、DOMツリーにおけるノード間の位置関係を示すDom\Node::DOCUMENT_POSITION_DISCONNECTED定数の使い方を解説しています。この定数は、Dom\NodeクラスのcompareDocumentPosition()メソッドの戻り値として利用されるビットマスクの一つです。

Dom\Node::DOCUMENT_POSITION_DISCONNECTEDは、比較対象となる二つのノードが同じドキュメントに所属していない、つまり「切断された」状態にある場合に、compareDocumentPosition()メソッドが返す値に含まれるフラグです。この「disposition」というキーワードは、DOMツリー内でのノードの配置状態や接続関係を指すものと解釈できます。

サンプルコードでは、まず新しいDOMドキュメントとそれに接続されたノードを作成します。次に、どのドキュメントにも追加されていない「切断された」ノードを用意し、接続されたノードとの比較を行います。compareDocumentPosition()メソッドの戻り値に対し、この定数でビットAND演算を行うことで、ノードが切断状態にあるかどうかの判定が可能です。同じドキュメント内に存在するノード同士の比較ではこのフラグが検出されず、異なるドキュメントに属するか、どちらかのノードがどのドキュメントにも追加されていない場合に検出されることが示されています。この例を通して、システムエンジニアを目指す初心者がDOMノードの接続状態を正確に理解し、プログラムでその関係性を判断する方法を学ぶことができます。