【PHP8.x】Dom\Notation::DOCUMENT_POSITION_CONTAINED_BY定数の使い方

Copy
1<?php
2
3/**
4 * DOMノードの位置関係を比較する定数 DOM_DOCUMENT_POSITION_CONTAINED_BY および
5 * DOM_DOCUMENT_POSITION_PRECEDING の使用例を示します。
6 *
7 * PHPのDOM拡張において、Dom\Node クラスとその派生クラス（Dom\Elementなど）は
8 * compareDocumentPosition メソッドを持ち、2つのノード間の位置関係を比較できます。
9 * このメソッドは、参照ノードに対する比較対象ノードの位置を示すビットマスクを返します。
10 *
11 * ここで示されている定数（DOM_DOCUMENT_POSITION_CONTAINED_BY など）は、
12 * Dom\Node クラス定数として定義されており、その動作は Dom\Notation インスタンスを含む
13 * すべての Dom\Node オブジェクトに適用されます。
14 *
15 * @see https://www.php.net/manual/ja/class.domnode.php#domnode.constants.document-position
16 */
17function demonstrateDomNodePositionComparison(): void
18{
19    // DOMDocument オブジェクトを作成し、整形出力を有効にする
20    $dom = new DOMDocument();
21    $dom->formatOutput = true;
22
23    // ドキュメントのルート要素を作成
24    $root = $dom->createElement('root');
25    $dom->appendChild($root);
26
27    // 親子関係を持つ要素を作成し、DOMツリーに追加
28    // この構造を使ってノード間の位置関係を比較します。
29    // <root>
30    //   <parent>
31    //     <child1>
32    //       <grandchild />
33    //     </child1>
34    //     <child2 />
35    //   </parent>
36    // </root>
37    $parent = $dom->createElement('parent');
38    $root->appendChild($parent);
39
40    $child1 = $dom->createElement('child1');
41    $parent->appendChild($child1);
42
43    $child2 = $dom->createElement('child2');
44    $parent->appendChild($child2);
45
46    $grandchild = $dom->createElement('grandchild');
47    $child1->appendChild($grandchild);
48
49    echo "--- DOM ノードの位置関係の比較 ---\n\n";
50
51    // 例1: $child1 と $parent の関係を比較
52    // $child1 は $parent に「含まれています」
53    $position1 = $child1->compareDocumentPosition($parent);
54    echo "1. \$child1 と \$parent の関係:\n";
55    // DOM_DOCUMENT_POSITION_CONTAINED_BY は、比較対象のノードが参照ノードに「含まれている」ことを示す定数です。
56    if (($position1 & DOM_DOCUMENT_POSITION_CONTAINED_BY) === DOM_DOCUMENT_POSITION_CONTAINED_BY) {
57        echo "   - \$child1 は \$parent に含まれています (DOM_DOCUMENT_POSITION_CONTAINED_BY)。\n";
58    }
59    // DOM_DOCUMENT_POSITION_CONTAINS は逆の関係（参照ノードが比較対象ノードを含んでいる）を示す定数です。
60    if (($position1 & DOM_DOCUMENT_POSITION_CONTAINS) === DOM_DOCUMENT_POSITION_CONTAINS) {
61        echo "   - \$child1 は \$parent を含んでいます (DOM_DOCUMENT_POSITION_CONTAINS)。\n";
62    }
63    echo "\n";
64
65    // 例2: $parent と $child1 の関係を比較
66    // $parent は $child1 を「含んでいます」
67    $position2 = $parent->compareDocumentPosition($child1);
68    echo "2. \$parent と \$child1 の関係:\n";
69    // ここでは DOM_DOCUMENT_POSITION_CONTAINS が適用されます。
70    if (($position2 & DOM_DOCUMENT_POSITION_CONTAINS) === DOM_DOCUMENT_POSITION_CONTAINS) {
71        echo "   - \$parent は \$child1 を含んでいます (DOM_DOCUMENT_POSITION_CONTAINS)。\n";
72    }
73    echo "\n";
74
75    // 例3: $child1 と $child2 の関係を比較
76    // $child1 は $child2 より「前に位置する」
77    $position3 = $child1->compareDocumentPosition($child2);
78    echo "3. \$child1 と \$child2 (同じ親を持つ兄弟ノード) の関係:\n";
79    // DOM_DOCUMENT_POSITION_PRECEDING は、比較対象のノードが参照ノードより
80    // ドキュメント順（ツリー構造での出現順）で「前に位置する」ことを示す定数です。
81    if (($position3 & DOM_DOCUMENT_POSITION_PRECEDING) === DOM_DOCUMENT_POSITION_PRECEDING) {
82        echo "   - \$child1 は \$child2 より前に位置します (DOM_DOCUMENT_POSITION_PRECEDING)。\n";
83    }
84    // DOM_DOCUMENT_POSITION_FOLLOWING は逆の関係（参照ノードより後に位置する）を示す定数です。
85    if (($position3 & DOM_DOCUMENT_POSITION_FOLLOWING) === DOM_DOCUMENT_POSITION_FOLLOWING) {
86        echo "   - \$child1 は \$child2 より後に位置します (DOM_DOCUMENT_POSITION_FOLLOWING)。\n";
87    }
88    echo "\n";
89
90    // 例4: 同じノードの比較
91    // 同じノードを比較した場合、compareDocumentPosition は 0 を返します。
92    $position4 = $child1->compareDocumentPosition($child1);
93    echo "4. \$child1 と \$child1 (同じノード) の関係:\n";
94    if ($position4 === 0) {
95        echo "   - これらは同じノードです (戻り値 0)。\n";
96    }
97    echo "\n";
98}
99
100// 定義した関数を実行します。
101demonstrateDomNodePositionComparison();
102

このサンプルコードは、PHPのDOM拡張機能を用いて、HTMLやXMLなどのツリー構造を持つ文書における要素（DOMノード）間の位置関係を比較する方法を解説しています。主に、Dom\Nodeクラスが持つcompareDocumentPositionメソッドと、その戻り値を判定するための定数を使用します。

compareDocumentPositionメソッドは、呼び出し元のノード（参照ノード）に対する引数のノード（比較対象ノード）の相対的な位置を示すビットマスクと呼ばれる数値を返します。このメソッド自体は引数を取りません。

そして、この数値を解釈するためにDOM_DOCUMENT_POSITION_CONTAINED_BYやDOM_DOCUMENT_POSITION_PRECEDINGといった定数が利用されます。例えば、DOM_DOCUMENT_POSITION_CONTAINED_BYは、比較対象ノードが参照ノードの内部に存在する場合に一致します。一方、DOM_DOCUMENT_POSITION_PRECEDINGは、比較対象ノードが参照ノードよりも文書の順序で先に位置する場合に一致します。これらの定数は引数を取らず、特定の状態を示す値そのものです。

この機能を使うことで、ノードが親であるか子であるか、あるいは兄弟ノードの中でどちらが先に現れるかなど、DOMツリー内の複雑なノード間の関係をプログラムで正確に判断できるようになります。

Copy
1<?php
2
3/**
4 * DOMノードの位置関係を比較し、一方のノードが他方に含まれているかを示すサンプルコードです。
5 *
6 * DOMNode::compareDocumentPosition() メソッドと
7 * DOM_DOCUMENT_POSITION_CONTAINED_BY 定数の使用方法を示します。
8 * この定数は、あるノードが別のノードによって「包含されている」状態を識別します。
9 */
10function demonstrateDocumentPositionContainedBy(): void
11{
12    // DOMDocumentオブジェクトを作成し、HTMLコンテンツをロードします。
13    $dom = new DOMDocument();
14    // HTMLパース時の警告を抑制します。
15    libxml_use_internal_errors(true);
16    $dom->loadHTML('
17        <div id="parent">
18            <p id="child">これは子要素です。</p>
19        </div>
20        <span id="sibling">これは兄弟要素です。</span>
21    ');
22    libxml_use_internal_errors(false);
23
24    // 比較対象となるノードを取得します。
25    $parentNode = $dom->getElementById('parent');
26    $childNode = $dom->getElementById('child');
27    $siblingNode = $dom->getElementById('sibling');
28
29    if (!$parentNode || !$childNode || !$siblingNode) {
30        echo "必要なノードが見つかりませんでした。HTMLのIDを確認してください。\n";
31        return;
32    }
33
34    echo "--- DOMノードの包含関係の比較 (DOCUMENT_POSITION_CONTAINED_BY) ---\n\n";
35
36    // ケース1: 子ノードが親ノードに「包含されている」かを確認します。
37    // compareDocumentPosition() は、呼び出し元のノード（$childNode）に対する
38    // 引数のノード（$parentNode）の位置関係を示すビットマスクを返します。
39    // $childNode は $parentNode に含まれているため、結果には DOM_DOCUMENT_POSITION_CONTAINED_BY が含まれます。
40    $positionChildToParent = $childNode->compareDocumentPosition($parentNode);
41    echo "1. '#child' ノードが '#parent' ノードに包含されているか？\n";
42    echo "   比較結果ビットマスク: " . $positionChildToParent . "\n";
43    echo "   (DOM_DOCUMENT_POSITION_CONTAINED_BY の値: " . DOM_DOCUMENT_POSITION_CONTAINED_BY . ")\n";
44    if (($positionChildToParent & DOM_DOCUMENT_POSITION_CONTAINED_BY) === DOM_DOCUMENT_POSITION_CONTAINED_BY) {
45        echo "   -> はい、'#child' は '#parent' に包含されています。\n";
46    } else {
47        echo "   -> いいえ、'#child' は '#parent' に包含されていません。\n";
48    }
49    echo "\n";
50
51    // ケース2: 親ノードが子ノードに「包含されている」かを確認します。
52    // 通常、親ノードが子ノードに包含されることはありません。
53    // 結果には DOM_DOCUMENT_POSITION_CONTAINED_BY は含まれません。
54    $positionParentToChild = $parentNode->compareDocumentPosition($childNode);
55    echo "2. '#parent' ノードが '#child' ノードに包含されているか？\n";
56    echo "   比較結果ビットマスク: " . $positionParentToChild . "\n";
57    if (($positionParentToChild & DOM_DOCUMENT_POSITION_CONTAINED_BY) === DOM_DOCUMENT_POSITION_CONTAINED_BY) {
58        echo "   -> はい、'#parent' は '#child' に包含されています。(この結果は稀です)\n";
59    } else {
60        echo "   -> いいえ、'#parent' は '#child' に包含されていません。\n";
61        // 補足: この場合、DOM_DOCUMENT_POSITION_CONTAINS が含まれるはずです。
62        if (($positionParentToChild & DOM_DOCUMENT_POSITION_CONTAINS) === DOM_DOCUMENT_POSITION_CONTAINS) {
63            echo "      (#parent は '#child' を含んでいます (DOM_DOCUMENT_POSITION_CONTAINS: " . DOM_DOCUMENT_POSITION_CONTAINS . ").)\n";
64        }
65    }
66    echo "\n";
67
68    // ケース3: 兄弟ノードが親ノードに「包含されている」かを確認します。
69    // 兄弟ノードは親ノードの外にあるため、包含されません。
70    $positionSiblingToParent = $siblingNode->compareDocumentPosition($parentNode);
71    echo "3. '#sibling' ノードが '#parent' ノードに包含されているか？\n";
72    echo "   比較結果ビットマスク: " . $positionSiblingToParent . "\n";
73    if (($positionSiblingToParent & DOM_DOCUMENT_POSITION_CONTAINED_BY) === DOM_DOCUMENT_POSITION_CONTAINED_BY) {
74        echo "   -> はい、'#sibling' は '#parent' に包含されています。(この結果は稀です)\n";
75    } else {
76        echo "   -> いいえ、'#sibling' は '#parent' に包含されていません。\n";
77        // この場合、DOM_DOCUMENT_POSITION_DISCONNECTED や DOM_DOCUMENT_POSITION_FOLLOWING が含まれる可能性があります。
78        if (($positionSiblingToParent & DOM_DOCUMENT_POSITION_DISCONNECTED) === DOM_DOCUMENT_POSITION_DISCONNECTED) {
79            echo "      (#sibling と #parent は同じツリーの一部ではないと見なされます。)\n";
80        }
81    }
82    echo "\n";
83}
84
85// 関数の実行
86demonstrateDocumentPositionContainedBy();

このサンプルコードは、PHPのDOM拡張機能を利用して、HTMLドキュメント内のノード（要素）同士の相対的な位置関係、特に「包含関係」をプログラムで確認する方法を説明しています。

中心となるのは、DOMNode::compareDocumentPosition()メソッドと、その戻り値の一部として使用されるDOM_DOCUMENT_POSITION_CONTAINED_BY定数です。DOMNode::compareDocumentPosition()メソッドは、比較元のノードと引数で指定された別のノードとの位置関係を、ビットマスク形式の数値で返します。この戻り値は、複数の状態を同時に表現できる特徴を持っています。

DOM_DOCUMENT_POSITION_CONTAINED_BY定数は、特定のノードが別のノードによって「包含されている」、つまりその内部にある子孫要素である状態を示すビットパターンを表します。この定数自体には引数や戻り値はありませんが、compareDocumentPosition()メソッドの戻り値に対してビット論理積演算子（&）を適用することで、目的の包含関係が成立しているかどうかを判定できます。

サンプルコードでは、まずHTML構造を持つDOMDocumentオブジェクトを作成します。次に、#parent、#child、#siblingというIDを持つノードを取得し、それらの包含関係を様々なパターンで比較しています。例えば、#childノードが#parentノードに包含されているかを正確に判定し、その結果を表示しています。これにより、ウェブページの複雑な構造を解析したり、特定の要素の親子関係を確認したりする際に役立つ技術を学ぶことができます。