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

Copy
1<?php
2
3// PHP 8
4// Dom\Node::DOCUMENT_POSITION_CONTAINED_BY 定数の使用例
5
6/**
7 * Dom\Node::DOCUMENT_POSITION_CONTAINED_BY 定数と
8 * Dom\Node::DOCUMENT_POSITION_PRECEDING 定数を含むノード位置比較のデモンストレーション。
9 *
10 * この関数は、DOMツリー内のノード間の相対位置を比較する方法を示します。
11 * Dom\Node::compareDocumentPosition() メソッドが返すビットマスクを解析し、
12 * 各定数がどのような意味を持つかを初心者にも分かりやすく説明します。
13 */
14function demonstrateDomNodePositionComparison(): void
15{
16    // 1. 新しいDOMドキュメントを初期化し、シンプルなXML構造を作成します。
17    //    親ノードが子ノードを包含する構造です。
18    //    例: <root><parent id="p1"><child id="c1"/></parent></root>
19    $dom = new DOMDocument();
20    $dom->loadXML('<root><parent id="p1"><child id="c1"/></parent></root>');
21
22    // 2. 比較対象となるノードをIDで取得します。
23    $parent = $dom->getElementById('p1');
24    $child = $dom->getElementById('c1');
25
26    // ノードが正しく取得できたか確認します。
27    if (!$parent instanceof Dom\Node || !$child instanceof Dom\Node) {
28        echo "エラー: parent または child ノードが見つかりませんでした。デモンストレーションを終了します。\n";
29        return;
30    }
31
32    echo "--- Dom\\Node::compareDocumentPosition() デモンストレーション ---\n\n";
33
34    // シナリオ 1: 子ノードが親ノードによって包含されているかを確認します。
35    // `$child` ノード (対象) と `$parent` ノード (比較対象) を比較します。
36    // 結果として、`$child` は `$parent` によって「包含されている」はずです。
37    $resultChildVsParent = $child->compareDocumentPosition($parent);
38
39    echo "シナリオ 1: 子ノード (`child`) と親ノード (`parent`) の比較\n";
40    echo "  \$child->compareDocumentPosition(\$parent) の結果 (ビットマスク): " . $resultChildVsParent . "\n";
41
42    // Dom\Node::DOCUMENT_POSITION_CONTAINED_BY は、対象ノードが比較ノードの子孫である場合に
43    // 結果のビットマスクに設定されるフラグです。
44    // bitwise AND演算子 `&` を使って、この特定のフラグが結果に含まれているかを確認します。
45    if (($resultChildVsParent & Dom\Node::DOCUMENT_POSITION_CONTAINED_BY) === Dom\Node::DOCUMENT_POSITION_CONTAINED_BY) {
46        echo "  [OK] `Dom\\Node::DOCUMENT_POSITION_CONTAINED_BY` フラグが設定されています。\n";
47        echo "       これは、`child` ノードが `parent` ノードに包含されている (子孫である) ことを意味します。\n";
48    } else {
49        echo "  [NG] `Dom\\Node::DOCUMENT_POSITION_CONTAINED_BY` フラグが設定されていません。\n";
50    }
51
52    // 補足: `$child` は `$parent` の子孫であるため、`DOCUMENT_POSITION_FOLLOWING` も設定されます。
53    // (対象ノードが比較ノードの子孫である、またはドキュメント順序で後に位置する場合)
54    if (($resultChildVsParent & Dom\Node::DOCUMENT_POSITION_FOLLOWING) === Dom\Node::DOCUMENT_POSITION_FOLLOWING) {
55        echo "  [補足] `Dom\\Node::DOCUMENT_POSITION_FOLLOWING` フラグも設定されています。\n";
56    }
57
58    echo "\n--------------------------------------------------------------\n\n";
59
60    // シナリオ 2: 親ノードが子ノードを包含しているか、またはドキュメント順序で前に位置するかを確認します。
61    // `$parent` ノード (対象) と `$child` ノード (比較対象) を比較します。
62    // 結果として、`$parent` は `$child` を「包含している」はずであり、
63    // また `$child` の「前に位置する」はずです。
64    $resultParentVsChild = $parent->compareDocumentPosition($child);
65
66    echo "シナリオ 2: 親ノード (`parent`) と子ノード (`child`) の比較\n";
67    echo "  \$parent->compareDocumentPosition(\$child) の結果 (ビットマスク): " . $resultParentVsChild . "\n";
68
69    // Dom\Node::DOCUMENT_POSITION_CONTAINS は、対象ノードが比較ノードの祖先である場合に設定されるフラグです。
70    if (($resultParentVsChild & Dom\Node::DOCUMENT_POSITION_CONTAINS) === Dom\Node::DOCUMENT_POSITION_CONTAINS) {
71        echo "  [OK] `Dom\\Node::DOCUMENT_POSITION_CONTAINS` フラグが設定されています。\n";
72        echo "       これは、`parent` ノードが `child` ノードを包含している (祖先である) ことを意味します。\n";
73    } else {
74        echo "  [NG] `Dom\\Node::DOCUMENT_POSITION_CONTAINS` フラグが設定されていません。\n";
75    }
76
77    // Dom\Node::DOCUMENT_POSITION_PRECEDING は、対象ノードが比較ノードの祖先であるか、
78    // またはドキュメント順序で比較ノードの前に位置する場合に設定されるフラグです。
79    // これはキーワードとして指定されたため、ここでその関連性をデモンストレーションします。
80    if (($resultParentVsChild & Dom\Node::DOCUMENT_POSITION_PRECEDING) === Dom\Node::DOCUMENT_POSITION_PRECEDING) {
81        echo "  [OK] `Dom\\Node::DOCUMENT_POSITION_PRECEDING` フラグが設定されています。\n";
82        echo "       これは、`parent` ノードが `child` ノードの前に位置するか、その祖先であることを意味します。\n";
83    } else {
84        echo "  [NG] `Dom\\Node::DOCUMENT_POSITION_PRECEDING` フラグが設定されていません。\n";
85    }
86}
87
88// デモンストレーションを実行します。
89demonstrateDomNodePositionComparison();

PHPのDom\Node::DOCUMENT_POSITION_CONTAINED_BYは、DOMツリー上のノード間の相対位置を示す整数定数の一つです。この定数は、主にDom\NodeクラスのcompareDocumentPosition()メソッドが返すビットマスクの結果を解析する際に使用されます。

compareDocumentPosition()メソッドは、あるノードが別のノードに対してどのような位置関係にあるかを示す整数値（ビットマスク）を戻り値として返します。このとき、比較対象のノード（引数として渡されるノード）が、メソッドを呼び出すノード（対象ノード）に「包含されている」、つまり対象ノードの子孫である場合に、戻り値のビットマスクにDOCUMENT_POSITION_CONTAINED_BYのフラグが設定されます。

サンプルコードでは、親ノードと子ノードを作成し、子ノードから親ノードを比較しています。その結果がDOCUMENT_POSITION_CONTAINED_BYを含んでいることを確認することで、「子ノードが親ノードに包含されている」という事実をプログラムで判定しています。

また、キーワードとして挙げられているDom\Node::DOCUMENT_POSITION_PRECEDINGも同様にビットマスクのフラグで、対象ノードが比較ノードの祖先であるか、またはドキュメント順序で比較ノードの前に位置する場合に設定されます。サンプルコードでは、親ノードが子ノードを比較する際に、親ノードが子ノードを包含し、かつ子ノードの前に位置するため、このフラグも設定されることを示しています。これらの定数を用いることで、DOMツリー内の複雑なノードの位置関係を正確に把握し、プログラムで分岐処理を行うことが可能になります。

Copy
1<?php
2
3/**
4 * Dom\Node::DOCUMENT_POSITION_CONTAINED_BY 定数の使用例を示します。
5 *
6 * この定数は、Dom\Node::compareDocumentPosition() メソッドの戻り値の
7 * ビットマスクの一部として使用され、比較対象のノードが基準ノードに
8 * 含まれているかどうかを判断するために利用されます。
9 *
10 * (例: <parent><child/></parent> の場合、child は parent に含まれる)
11 */
12function demonstrateDocumentPositionContainedBy(): void
13{
14    // 1. DOMDocument を作成し、簡単なHTML構造を読み込みます。
15    $dom = new DOMDocument();
16    $dom->loadHTML('<div id="parent"><span id="child">Hello</span></div>');
17
18    // 2. 比較に使用するノードを取得します。
19    // getElementById は DOMElement を返します。DOMElement は Dom\Node の子孫クラスです。
20    $parentNode = $dom->getElementById('parent');
21    $childNode = $dom->getElementById('child');
22    // HTML全体の親となる body ノードも取得します。
23    $bodyNode = $dom->getElementsByTagName('body')->item(0);
24
25    // ノードが正しく取得できたかを確認します。
26    if (!$parentNode || !$childNode || !$bodyNode) {
27        echo "エラー: 必要なノードが見つかりませんでした。HTML構造を確認してください。\n";
28        return;
29    }
30
31    echo "--- Dom\\Node::DOCUMENT_POSITION_CONTAINED_BY の使用例 ---\n";
32
33    // 例1: 子ノードが親ノードに含まれているか確認する
34    // 基準ノード: $parentNode ('parent' div)
35    // 比較対象ノード: $childNode ('child' span)
36    echo "\n'parent' ノードを基準に 'child' ノードを比較:\n";
37    $position = $parentNode->compareDocumentPosition($childNode);
38    echo "compareDocumentPosition() の戻り値 (ビットマスク): " . $position . " (10進数)\n";
39
40    // ビット AND 演算子 (&) を使って、DOCUMENT_POSITION_CONTAINED_BY がセットされているかを確認します。
41    if (($position & Dom\Node::DOCUMENT_POSITION_CONTAINED_BY) === Dom\Node::DOCUMENT_POSITION_CONTAINED_BY) {
42        echo "結果: 'child' ノードは 'parent' ノードに含まれています。(期待値: はい)\n";
43    } else {
44        echo "結果: 'child' ノードは 'parent' ノードに含まれていません。(期待値: いいえ)\n";
45    }
46
47    // 例2: 親ノードが子ノードに含まれているか確認する (逆方向)
48    // 基準ノード: $childNode ('child' span)
49    // 比較対象ノード: $parentNode ('parent' div)
50    echo "\n'child' ノードを基準に 'parent' ノードを比較:\n";
51    // この場合、$parentNode は $childNode に含まれていません。
52    // 実際には、$childNode が $parentNode に含まれているため、
53    // DOCUMENT_POSITION_CONTAINS (親が子を含む) がセットされますが、
54    // DOCUMENT_POSITION_CONTAINED_BY (子が親に含まれる) はセットされません。
55    $position = $childNode->compareDocumentPosition($parentNode);
56    echo "compareDocumentPosition() の戻り値 (ビットマスク): " . $position . " (10進数)\n";
57
58    if (($position & Dom\Node::DOCUMENT_POSITION_CONTAINED_BY) === Dom\Node::DOCUMENT_POSITION_CONTAINED_BY) {
59        echo "結果: 'parent' ノードは 'child' ノードに含まれています。(期待値: いいえ)\n";
60    } else {
61        echo "結果: 'parent' ノードは 'child' ノードに含まれていません。(期待値: はい)\n";
62    }
63
64    // 例3: より上位のノードが子ノードを含んでいるか確認する
65    // 基準ノード: $bodyNode (HTML body要素)
66    // 比較対象ノード: $childNode ('child' span)
67    echo "\n'body' ノードを基準に 'child' ノードを比較:\n";
68    // $childNode は $bodyNode に含まれています。
69    $position = $bodyNode->compareDocumentPosition($childNode);
70    echo "compareDocumentPosition() の戻り値 (ビットマスク): " . $position . " (10進数)\n";
71
72    if (($position & Dom\Node::DOCUMENT_POSITION_CONTAINED_BY) === Dom\Node::DOCUMENT_POSITION_CONTAINED_BY) {
73        echo "結果: 'child' ノードは 'body' ノードに含まれています。(期待値: はい)\n";
74    } else {
75        echo "結果: 'child' ノードは 'body' ノードに含まれていません。(期待値: いいえ)\n";
76    }
77}
78
79// 定数の使用例を示す関数を実行します。
80demonstrateDocumentPositionContainedBy();

Dom\Node::DOCUMENT_POSITION_CONTAINED_BYは、PHPのDOM拡張機能における定数で、Webページの構造（Document Object Model）内でノードが他のノードとどのような位置関係にあるかを示す整数値です。この定数自体に引数はなく、内部的に特定の整数値を保持しています。

この定数は、主にDom\Node::compareDocumentPosition()メソッドの戻り値を解釈するために利用されます。compareDocumentPosition()メソッドは、あるノードを基準として、別のノードがその基準ノードに対してどの位置にあるかを示すビットマスク（複数の状態を同時に表す整数）を返します。

具体的には、返されたビットマスクとDom\Node::DOCUMENT_POSITION_CONTAINED_BY定数をビットAND演算子&で比較することで、比較対象のノードが基準となるノードの中に含まれている（つまり、基準ノードの子孫ノードである）かどうかを判断できます。

サンプルコードでは、まずHTML構造を作成し、親要素と子要素、さらに上位のbody要素を取得しています。'parent'ノードを基準に'child'ノードを比較すると、'child'は'parent'に含まれるため、compareDocumentPosition()の戻り値にDOCUMENT_POSITION_CONTAINED_BYのビットがセットされます。しかし、'child'ノードを基準に'parent'ノードを比較する逆のケースでは、'parent'は'child'に含まれないため、このビットはセットされません。このように、ノード間の包含関係を正確に判定する際に役立つ定数です。