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

Copy
1<?php
2
3/**
4 * 二つのDOMノード間の相対位置を比較し、結果を表示する関数。
5 * DOMNode::compareDocumentPosition() メソッドを使用し、
6 * 定数（DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_PRECEDING など）
7 * に基づいて位置関係を解釈します。
8 *
9 * @param DOMNode $nodeA 比較する最初のノード
10 * @param DOMNode $nodeB 比較する二番目のノード
11 * @return void
12 */
13function describeNodePositions(DOMNode $nodeA, DOMNode $nodeB): void
14{
15    // 比較するノードの名前を取得します。
16    $nameA = $nodeA->nodeName;
17    $nameB = $nodeB->nodeName;
18
19    echo "--- 比較: '{$nameA}' と '{$nameB}' ---\n";
20
21    // DOMNode::compareDocumentPosition() を使用して、二つのノード間の位置を比較します。
22    // このメソッドは、ノード間の関係を示すビットマスクの整数値を返します。
23    $position = $nodeA->compareDocumentPosition($nodeB);
24
25    echo "結果のビットマスク値: " . $position . "\n";
26
27    // ビットマスクと DOMElement::DOCUMENT_POSITION_CONTAINED_BY 定数をビット論理積 (&) で比較し、
28    // $nodeA が $nodeB に含まれているか（$nodeBの子孫であるか）を判断します。
29    if ($position & DOMNode::DOCUMENT_POSITION_CONTAINED_BY) {
30        echo " - '{$nameA}' は '{$nameB}' に含まれています (子孫要素)\n";
31    }
32
33    // DOMElement::DOCUMENT_POSITION_PRECEDING 定数と比較し、
34    // $nodeA が $nodeB よりDOMツリー上で前に出現するかを判断します。
35    if ($position & DOMNode::DOCUMENT_POSITION_PRECEDING) {
36        echo " - '{$nameA}' は '{$nameB}' よりDOMツリー上で前にあります\n";
37    }
38
39    // 参考: その他の主要な位置関係も確認できます。
40
41    // $nodeA が $nodeB を含んでいるか（$nodeBの祖先であるか）
42    if ($position & DOMNode::DOCUMENT_POSITION_CONTAINS) {
43        echo " - '{$nameA}' は '{$nameB}' を含んでいます (祖先要素)\n";
44    }
45
46    // $nodeA が $nodeB よりDOMツリー上で後に出現するか
47    if ($position & DOMNode::DOCUMENT_POSITION_FOLLOWING) {
48        echo " - '{$nameA}' は '{$nameB}' よりDOMツリー上で後にあります\n";
49    }
50
51    // $position が 0 の場合、両方のノードが同じであることを示します。
52    if ($position === 0) {
53        echo " - '{$nameA}' と '{$nameB}' は同じノードです\n";
54    }
55
56    echo "\n";
57}
58
59// 新しいDOMドキュメントを作成し、HTML構造を構築します。
60$dom = new DOMDocument('1.0', 'UTF-8');
61$dom->formatOutput = true; // 出力を整形して見やすくします
62
63// HTML構造の構築: html -> body -> p (paragraph1) -> span
64//                                   -> p (paragraph2)
65
66$html = $dom->createElement('html');
67$dom->appendChild($html);
68
69$body = $dom->createElement('body');
70$html->appendChild($body);
71
72$paragraph1 = $dom->createElement('p');
73$paragraph1->textContent = 'これは最初の段落です。';
74$body->appendChild($paragraph1);
75
76$span = $dom->createElement('span');
77$span->textContent = 'インラインテキスト';
78$paragraph1->appendChild($span); // spanはparagraph1の子要素です
79
80$paragraph2 = $dom->createElement('p');
81$paragraph2->textContent = 'これは二番目の段落です。';
82$body->appendChild($paragraph2); // paragraph2はbodyの子要素であり、paragraph1の後に続きます
83
84// 構築したDOMツリーの確認 (必要であればコメント解除)
85// echo $dom->saveXML();
86
87// 異なるノード間の位置関係を比較し、結果を表示します。
88
89// 例1: $paragraph1 は $body に含まれているか？
90describeNodePositions($paragraph1, $body);
91
92// 例2: $body は $paragraph1 を含んでいるか？
93describeNodePositions($body, $paragraph1);
94
95// 例3: $span は $paragraph1 に含まれているか？
96describeNodePositions($span, $paragraph1);
97
98// 例4: $paragraph1 は $span を含んでいるか？
99describeNodePositions($paragraph1, $span);
100
101// 例5: $paragraph1 は $paragraph2 より前に出現するか？
102describeNodePositions($paragraph1, $paragraph2);
103
104// 例6: $paragraph2 は $paragraph1 より前に出現するか？ (逆の関係)
105describeNodePositions($paragraph2, $paragraph1);
106
107// 例7: 同じノードの比較
108describeNodePositions($paragraph1, $paragraph1);

このPHPコードは、ウェブページの構造を表現するDOM（Document Object Model）ツリー内で、二つのノード（要素やテキストなど）がどのような相対的な位置関係にあるかを調べる方法を示しています。この機能の中心となるのは、DOMNodeクラスに用意されているcompareDocumentPosition()メソッドです。

compareDocumentPosition()メソッドは、引数として渡されたノードBに対して、呼び出し元のノードAがツリー上でどのような位置にあるかを示す整数値を返します。この戻り値はビットマスクと呼ばれる形式で、複数の位置関係が同時に表現されている可能性があります。コードでは、この戻り値と、DOMNode::DOCUMENT_POSITION_CONTAINED_BYやDOMNode::DOCUMENT_POSITION_PRECEDINGといった定数をビット論理積（&）で比較することで、具体的な関係性を判定しています。

例えば、DOCUMENT_POSITION_CONTAINED_BYは、ノードAがノードBの「子孫要素」、つまりノードBの中に含まれている場合に真となります。また、DOCUMENT_POSITION_PRECEDINGは、ノードAがノードBよりもDOMツリー上で「先に記述されている」ことを示します。他にも、ノードAがノードBを「含んでいる」か（DOCUMENT_POSITION_CONTAINS）や、ノードAがノードBの「後に続く」か（DOCUMENT_POSITION_FOLLOWING）なども確認可能です。

サンプルコードでは、まずHTML構造を持つDOMドキュメントを作成し、その後、複数の異なるノードの組み合わせに対して比較関数を呼び出しています。これにより、作成した関数describeNodePositionsが、例えばparagraph1とbody、spanとparagraph1といった具体的なノード間で、どのような位置関係を検出して出力するのかを実際に確認できます。この機能は、DOMツリーの構造を解析したり、特定の要素の位置に基づいて処理を分岐させたりする際に非常に役立ちます。

Copy
1<?php
2
3/**
4 * DOMElement::DOCUMENT_POSITION_CONTAINED_BY 定数を使用して、
5 * DOM ノード間の包含関係を判定するサンプルコードです。
6 *
7 * この定数は、DOMNode::compareDocumentPosition メソッドの戻り値と組み合わせて使用され、
8 * 比較対象のノードが基準ノードに「含まれている」場合にセットされるビットフラグを示します。
9 * システムエンジニアを目指す初心者の方にも理解しやすいように、具体的なHTML構造と
10 * ノードの比較を通じてその使い方を示します。
11 */
12function demonstrateDocumentPositionContainedBy(): void
13{
14    // 1. DOMDocument オブジェクトを作成し、HTML をロードします。
15    $dom = new DOMDocument();
16    // LIBXML_HTML_NOIMPLIED と LIBXML_HTML_NODEFDTD を使用して、
17    // 自動で追加される不要なタグ（<html>, <body>など）を抑制し、シンプルなDOMを構築します。
18    $dom->loadHTML('<div id="parent-element"><p id="child-element">子要素</p></div>', LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD);
19
20    // 2. 比較対象となる DOMElement ノードを取得します。
21    // 親要素と子要素のノードをそれぞれのIDで取得します。
22    $parentElement = $dom->getElementById('parent-element');
23    $childElement = $dom->getElementById('child-element');
24
25    // ノードが正しく取得できたかを確認します。
26    if (!$parentElement || !$childElement) {
27        echo "エラー: 必要なDOM要素が見つかりませんでした。\n";
28        return;
29    }
30
31    echo "--- ノードの包含関係の判定 ---\n";
32    echo "親要素 (ID: parent-element) と 子要素 (ID: child-element) の関係を比較します。\n\n";
33
34    // 3. DOMNode::compareDocumentPosition メソッドを使用してノードの位置関係を比較します。
35    // compareDocumentPosition は、メソッドを呼び出したノード (基準ノード) と
36    // 引数で渡されたノード (比較対象ノード) の相対的な位置関係を示すビットマスクを返します。
37    // ここでは、$parentElement を基準として $childElement の位置関係を調べます。
38    $positionResult = $parentElement->compareDocumentPosition($childElement);
39
40    echo "比較元: \$parentElement (ID: parent-element)\n";
41    echo "比較対象: \$childElement (ID: child-element)\n";
42    echo "compareDocumentPosition の戻り値 (ビットマスク): " . $positionResult . "\n\n";
43
44    // 4. DOCUMENT_POSITION_CONTAINED_BY 定数と戻り値をビット論理積 (&) で比較します。
45    // DOCUMENT_POSITION_CONTAINED_BY は、比較対象ノードが基準ノードの「内部に」ある場合に
46    // 戻り値のビットマスクに含まれるフラグです。
47    // ビット論理積の結果が定数と同じ値であれば、そのフラグがセットされていることになります。
48    if (($positionResult & DOMElement::DOCUMENT_POSITION_CONTAINED_BY) === DOMElement::DOCUMENT_POSITION_CONTAINED_BY) {
49        echo "判定結果: \$childElement は \$parentElement の内部に含まれています。\n";
50        echo "理由: compareDocumentPosition の戻り値に DOMElement::DOCUMENT_POSITION_CONTAINED_BY フラグがセットされています。\n";
51    } else {
52        echo "判定結果: \$childElement は \$parentElement の内部に含まれていません。\n";
53        echo "理由: compareDocumentPosition の戻り値に DOMElement::DOCUMENT_POSITION_CONTAINED_BY フラグがセットされていません。\n";
54    }
55    echo "\n";
56
57    // 5. 関連のないノードでの比較 (参考)
58    // 別のHTML構造をロードし、互いに包含関係を持たないノードを比較します。
59    $dom->loadHTML('<div id="first-element">最初の要素</div><p id="second-element">2番目の要素</p>', LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD);
60    $firstElement = $dom->getElementById('first-element');
61    $secondElement = $dom->getElementById('second-element');
62
63    if ($firstElement && $secondElement) {
64        echo "--- 関連のないノードでの比較 (参考) ---\n";
65        echo "比較元: \$firstElement (ID: first-element)\n";
66        echo "比較対象: \$secondElement (ID: second-element)\n";
67
68        $unrelatedPositionResult = $firstElement->compareDocumentPosition($secondElement);
69        echo "compareDocumentPosition の戻り値 (ビットマスク): " . $unrelatedPositionResult . "\n\n";
70
71        if (($unrelatedPositionResult & DOMElement::DOCUMENT_POSITION_CONTAINED_BY) === DOMElement::DOCUMENT_POSITION_CONTAINED_BY) {
72            echo "判定結果: \$secondElement は \$firstElement の内部に含まれています。\n";
73        } else {
74            echo "判定結果: \$secondElement は \$firstElement の内部に含まれていません。\n";
75        }
76    }
77}
78
79// サンプル関数を実行
80demonstrateDocumentPositionContainedBy();

PHP 8のDOMElement::DOCUMENT_POSITION_CONTAINED_BYは、DOM（Document Object Model）におけるノード間の位置関係、特に「包含関係」を判定するための整数定数です。この定数自体は引数を取らず、特定の整数値を持ち、主にDOMNode::compareDocumentPositionメソッドの戻り値と組み合わせて使用されます。compareDocumentPositionメソッドは、呼び出し元のノード（基準ノード）と引数で渡されたノード（比較対象ノード）の相対的な位置関係を示すビットマスクを整数で返します。

サンプルコードでは、まずHTMLのDOM構造として親要素と子要素を作成し、それぞれのノードを取得しています。次に、親要素を基準ノードとしてcompareDocumentPositionメソッドで子要素との位置関係を比較し、その戻り値を取得します。この戻り値とDOMElement::DOCUMENT_POSITION_CONTAINED_BY定数をビット論理積（&）で比較することで、子要素が親要素の内部に含まれているかどうかを判定しています。この定数は、比較対象ノードが基準ノードの内部に完全に「含まれている」場合にcompareDocumentPositionの戻り値のビットマスクにセットされるフラグを示します。これにより、HTML要素の親子関係などをプログラムで正確に判別することが可能です。