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

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * DOMNode::compareDocumentPosition() メソッドと関連定数の使用例を示します。
7 *
8 * この関数は、簡単なXML構造を作成し、DOMノード間の相対的な位置を比較します。
9 * 特に、指定された定数 DOM_DOCUMENT_POSITION_CONTAINED_BY と、
10 * キーワードに関連する DOM_DOCUMENT_POSITION_PRECEDING の意味と使い方を説明します。
11 */
12function demonstrateDomNodePositionComparison(): void
13{
14    // 新しいDOMドキュメントを作成します。
15    // DOM (Document Object Model) は、HTMLやXML文書をプログラムで操作するためのAPIです。
16    $dom = new DOMDocument('1.0', 'UTF-8');
17    $dom->formatOutput = true; // 出力を整形するために設定します。
18
19    // ルート要素 <root> を作成し、ドキュメントに追加します。
20    $root = $dom->createElement('root');
21    $dom->appendChild($root);
22
23    // 子要素 <childA> を作成し、<root> に追加します。
24    $childA = $dom->createElement('childA');
25    $root->appendChild($childA);
26
27    // 子要素 <childB> を作成し、<root> に追加します。
28    $childB = $dom->createElement('childB');
29    $root->appendChild($childB);
30
31    // 孫要素 <grandchild> を作成し、<childA> に追加します。
32    $grandchild = $dom->createElement('grandchild');
33    $childA->appendChild($grandchild);
34
35    echo "--- DOMノードの相対位置の比較 --- \n";
36
37    // 1. ノードが他のノードに含まれるケース (DOM_DOCUMENT_POSITION_CONTAINED_BY)
38    // $grandchild は $childA に含まれています。
39    // $childA ノードが $grandchild ノードに対してどのような位置関係にあるかを比較します。
40    $positionGrandchildVsChildA = $childA->compareDocumentPosition($grandchild);
41
42    echo "\n'<childA>' と '<grandchild>' の比較:\n";
43    // DOM_DOCUMENT_POSITION_CONTAINED_BY をチェックします。
44    // compareDocumentPosition() の戻り値は、複数の状態を示すビットマスクです。
45    // ビット論理積演算子 (&) を使って、特定のフラグが立っているかを確認します。
46    // ここでは、$targetNode ($grandchild) が $thisNode ($childA) に含まれている場合に
47    // このフラグが設定されるかをチェックしています。
48    if (($positionGrandchildVsChildA & DOM_DOCUMENT_POSITION_CONTAINED_BY) === DOM_DOCUMENT_POSITION_CONTAINED_BY) {
49        echo "- '<grandchild>' は '<childA>' に含まれています。(DOM_DOCUMENT_POSITION_CONTAINED_BY)\n";
50    }
51
52    // 補足: 逆に $childA が $grandchild を含んでいるかを確認する場合は DOM_DOCUMENT_POSITION_CONTAINS を使用します。
53    if (($positionGrandchildVsChildA & DOM_DOCUMENT_POSITION_CONTAINS) === DOM_DOCUMENT_POSITION_CONTAINS) {
54        echo "- '<childA>' は '<grandchild>' を含んでいます。(DOM_DOCUMENT_POSITION_CONTAINS)\n";
55    }
56
57
58    // 2. ノードが他のノードの前に位置するケース (DOM_DOCUMENT_POSITION_PRECEDING)
59    // ドキュメントツリーでは、$childA が $childB の前に位置しています。
60    // $childB ノードが $childA ノードに対してどのような位置関係にあるかを比較します。
61    $positionChildAVsChildB = $childB->compareDocumentPosition($childA);
62
63    echo "\n'<childB>' と '<childA>' の比較:\n";
64    // DOM_DOCUMENT_POSITION_PRECEDING をチェックします。
65    // $targetNode ($childA) が $thisNode ($childB) の「前に」位置している場合にこのフラグが設定されます。
66    if (($positionChildAVsChildB & DOM_DOCUMENT_POSITION_PRECEDING) === DOM_DOCUMENT_POSITION_PRECEDING) {
67        echo "- '<childA>' は '<childB>' の前に位置しています。(DOM_DOCUMENT_POSITION_PRECEDING)\n";
68    } else {
69        echo "- '<childA>' は '<childB>' の前に位置していません（この比較では）。\n";
70    }
71
72    // 逆に、$childA が $childB に対してどのような位置関係にあるかを比較します。
73    // $childB は $childA の後に位置するため、DOM_DOCUMENT_POSITION_FOLLOWING が設定されます。
74    $positionChildBVsChildA = $childA->compareDocumentPosition($childB);
75    echo "\n'<childA>' と '<childB>' の比較:\n";
76    if (($positionChildBVsChildA & DOM_DOCUMENT_POSITION_FOLLOWING) === DOM_DOCUMENT_POSITION_FOLLOWING) {
77        echo "- '<childB>' は '<childA>' の後に位置しています。(DOM_DOCUMENT_POSITION_FOLLOWING)\n";
78    }
79
80
81    echo "\n--- 生成されたXML構造 ---\n";
82    echo $dom->saveXML();
83}
84
85// 関数を実行して、DOMノードの位置比較のデモンストレーションを開始します。
86demonstrateDomNodePositionComparison();

このPHPコードは、XML文書内の要素（ノード）の相対的な位置関係を比較する方法をデモンストレーションしています。DOM（Document Object Model）機能を利用して、プログラムでXML構造を操作し、ノード間の親子関係や順序関係を確認します。

DOMNode::compareDocumentPosition()メソッドは、引数で渡されたDOMノードが、このメソッドを呼び出したノードに対してどのような位置関係にあるかを示す整数値を返します。この戻り値は複数の状態を表すビットマスクであるため、DOM_DOCUMENT_POSITION_CONTAINED_BYのような定数とビット論理積（&）を組み合わせて、特定の関係性が存在するかどうかを判定します。

DOM_DOCUMENT_POSITION_CONTAINED_BY定数は、比較対象のノードが、このメソッドを呼び出したノードに「含まれている」場合に設定されるビットフラグです。例えば、親ノードが子ノードを比較する際に、子ノードが親ノードに含まれる状態を判定するために使用されます。

また、キーワードとして挙げられているDOM_DOCUMENT_POSITION_PRECEDING定数は、比較対象のノードが、このメソッドを呼び出したノードの「前に位置している」場合に設定されるビットフラグです。この定数も同様にcompareDocumentPosition()メソッドの戻り値と組み合わせて、ドキュメントツリーにおけるノードの順序関係を判定する際に利用されます。コードでは、これらの定数を使って、作成したXML構造におけるノード間の具体的な位置関係を判別し、その結果を出力しています。

Copy
1<?php
2
3/**
4 * DOMNode::DOCUMENT_POSITION_CONTAINED_BY 定数を使用して、
5 * 2つのDOMノード間の位置関係をデモンストレーションします。
6 *
7 * この定数は、DOMNode::compareDocumentPosition() メソッドの戻り値の一部として使用され、
8 * 比較対象のノード (引数で渡されたノード) が、呼び出し元のノードを「含んでいる」場合にセットされるビットマスクです。
9 *
10 * システムエンジニアを目指す初心者の方へ:
11 * DOM (Document Object Model) は、HTMLやXML文書をプログラムから操作するための標準的なAPIです。
12 * DOMツリー内のノードが互いに対してどのような位置関係にあるかを判断する際に、この定数が役立ちます。
13 */
14function demonstrateDocumentPositionContainedBy(): void
15{
16    // 1. DOMDocument オブジェクトを作成
17    //    これは、XML/HTML ドキュメント全体を表すコンテナです。
18    $dom = new DOMDocument();
19
20    // 2. ルート要素 'parent_element' を作成し、DOM に追加
21    //    このノードが「親」の役割を果たします。
22    $parentElement = $dom->createElement('parent_element');
23    $dom->appendChild($parentElement);
24
25    // 3. 子要素 'child_element' を作成し、'parent_element' の子として追加
26    //    このノードが「子」の役割を果たします。
27    $childElement = $dom->createElement('child_element');
28    $parentElement->appendChild($childElement);
29
30    // 4. DOM ツリーとは関係のない、別の要素 'unrelated_element' を作成
31    $unrelatedElement = $dom->createElement('unrelated_element');
32
33
34    echo "--- シナリオ 1: 子要素が親要素に「含まれている」ケース --- \n";
35    echo "比較対象: 'child_element' と 'parent_element'\n";
36
37    // childElement から見て parentElement がどのような位置関係にあるかを比較します。
38    // DOCUMENT_POSITION_CONTAINED_BY は、比較対象 ($parentElement) が
39    // 呼び出し元 ($childElement) を含んでいるかを示すビットマスクです。
40    $position1 = $childElement->compareDocumentPosition($parentElement);
41
42    // ビット AND 演算子 (&) を使って、戻り値に DOCUMENT_POSITION_CONTAINED_BY が含まれているかを確認します。
43    if ($position1 & DOMNode::DOCUMENT_POSITION_CONTAINED_BY) {
44        echo "結果: 'child_element' は 'parent_element' に「含まれています」。\n";
45        echo "これは、'parent_element' が 'child_element' を含んでいる状態を示します。\n";
46    } else {
47        echo "結果: 'child_element' は 'parent_element' に「含まれていません」。\n";
48    }
49    echo "\n";
50
51
52    echo "--- シナリオ 2: 互いに含まれていない要素同士の比較ケース --- \n";
53    echo "比較対象: 'child_element' と 'unrelated_element'\n";
54
55    // childElement から見て unrelatedElement がどのような位置関係にあるかを比較します。
56    // この場合、unrelatedElement は childElement を含んでいません。
57    $position2 = $childElement->compareDocumentPosition($unrelatedElement);
58
59    if ($position2 & DOMNode::DOCUMENT_POSITION_CONTAINED_BY) {
60        echo "結果: 'child_element' は 'unrelated_element' に「含まれています」。\n";
61    } else {
62        echo "結果: 'child_element' は 'unrelated_element' に「含まれていません」。\n";
63        echo "これは、'unrelated_element' が 'child_element' を含んでいないためです。\n";
64    }
65    echo "\n";
66}
67
68// 関数を実行してデモンストレーションを開始
69demonstrateDocumentPositionContainedBy();

PHPのDOMNode::DOCUMENT_POSITION_CONTAINED_BYは、DOM（Document Object Model）拡張機能で提供される定数です。DOMはHTMLやXML文書をプログラムから操作するための標準的なAPIであり、この定数自体に引数や戻り値はありません。主にDOMNode::compareDocumentPosition()メソッドの戻り値と組み合わせて使用され、ノード間の位置関係を判断する際に役立ちます。

compareDocumentPosition()メソッドは、引数で渡された別のノードと、メソッドを呼び出したノードとの間の相対的な位置関係を示すビットマスクを返します。DOCUMENT_POSITION_CONTAINED_BY定数は、その戻り値に含まれるビットの一つで、比較対象のノード（引数）が、メソッドを呼び出したノードを「含んでいる」状態を示します。

サンプルコードでは、この定数を用いて、子要素から親要素を比較した際に、親要素が子要素を含んでいるかどうかの判断を行っています。compareDocumentPosition()の戻り値とDOCUMENT_POSITION_CONTAINED_BY定数をビットAND演算（&）で評価することで、親要素が子要素を包含する関係にあるかを正確に判別できます。このように、DOMツリーにおける要素間の階層的な包含関係をプログラムで確認するために活用されます。