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

Copy
1<?php
2
3/**
4 * DOMノード間の位置関係を比較する関数。
5 *
6 * この関数は、Dom\Node::compareDocumentPosition() メソッドを使用し、
7 * 指定されたノード間の相対的な位置関係を判断します。
8 * 戻り値はビットマスクの整数値であり、Dom\Document クラスの定数
9 * (例: DOCUMENT_POSITION_PRECEDING, DOCUMENT_POSITION_CONTAINED_BY)
10 * とビット論理積(&)で比較することで、特定の位置関係を検出できます。
11 * 特に、キーワードである DOCUMENT_POSITION_PRECEDING と
12 * リファレンス情報にある DOCUMENT_POSITION_CONTAINED_BY の使用例を示します。
13 */
14function demonstrateNodePositionComparison(): void
15{
16    // 新しいDOMドキュメントを作成
17    $dom = new Dom\Document();
18    // DOMツリーの出力時に整形されるように設定（可読性向上）
19    $dom->formatOutput = true;
20
21    // ルート要素 'root' を作成し、ドキュメントに追加
22    $root = $dom->createElement('root');
23    $dom->appendChild($root);
24
25    // 子要素 'childA' と 'childB' を作成
26    $childA = $dom->createElement('childA');
27    $childB = $dom->createElement('childB');
28    // grandchild 要素を作成
29    $grandchild = $dom->createElement('grandchild');
30
31    // DOMツリーの階層構造を構築
32    // <root>
33    //   <childA>
34    //     <grandchild/>
35    //   </childA>
36    //   <childB/>
37    // </root>
38    $root->appendChild($childA);
39    $root->appendChild($childB);
40    $childA->appendChild($grandchild);
41
42    echo "--- DOM 構造 ---" . PHP_EOL;
43    echo $dom->saveHTML() . PHP_EOL;
44
45    echo "--- ノード位置比較の例 ---" . PHP_EOL;
46
47    // 例1: childA と childB の比較
48    // 「childA」は「childB」の「前に現れる」関係 (DOCUMENT_POSITION_PRECEDING) です。
49    // compareDocumentPosition() は、呼び出し元のノードが引数のノードに対してどのような位置にあるかを返します。
50    $positionA_B = $childA->compareDocumentPosition($childB);
51    echo "「childA」と「childB」の比較結果: " . $positionA_B . PHP_EOL;
52    if ($positionA_B & Dom\Document::DOCUMENT_POSITION_PRECEDING) {
53        echo "  -> 結果に DOCUMENT_POSITION_PRECEDING が含まれます。つまり、「childA」は「childB」の前に現れます。" . PHP_EOL;
54    } else {
55        echo "  -> 結果に DOCUMENT_POSITION_PRECEDING は含まれません。" . PHP_EOL;
56    }
57    echo PHP_EOL;
58
59    // 例2: grandchild と childA の比較
60    // 「grandchild」は「childA」に「含まれる」関係 (DOCUMENT_POSITION_CONTAINED_BY) です。
61    $positionGrandchild_ChildA = $grandchild->compareDocumentPosition($childA);
62    echo "「grandchild」と「childA」の比較結果: " . $positionGrandchild_ChildA . PHP_EOL;
63    if ($positionGrandchild_ChildA & Dom\Document::DOCUMENT_POSITION_CONTAINED_BY) {
64        echo "  -> 結果に DOCUMENT_POSITION_CONTAINED_BY が含まれます。つまり、「grandchild」は「childA」の中に含まれています。" . PHP_EOL;
65    } else {
66        echo "  -> 結果に DOCUMENT_POSITION_CONTAINED_BY は含まれません。" . PHP_EOL;
67    }
68    echo PHP_EOL;
69
70    // 例3: childB と grandchild の比較
71    // 「childB」は「grandchild」の「後に現れる」関係です。
72    // この場合、呼び出し元の「childB」は引数の「grandchild」の後に来るため、
73    // DOCUMENT_POSITION_PRECEDING は結果に含まれません。
74    $positionB_Grandchild = $childB->compareDocumentPosition($grandchild);
75    echo "「childB」と「grandchild」の比較結果: " . $positionB_Grandchild . PHP_EOL;
76    if ($positionB_Grandchild & Dom\Document::DOCUMENT_POSITION_PRECEDING) {
77        echo "  -> 結果に DOCUMENT_POSITION_PRECEDING が含まれます。(このケースでは通常該当しません)" . PHP_EOL;
78    } else {
79        echo "  -> 結果に DOCUMENT_POSITION_PRECEDING は含まれません。これは正しい挙動です。「childB」は「grandchild」の後に現れます。" . PHP_EOL;
80    }
81    echo PHP_EOL;
82}
83
84// 関数を実行して、DOMノード間の位置比較のデモンストレーションを行います
85demonstrateNodePositionComparison();

PHPのDom\Document::DOCUMENT_POSITION_CONTAINED_BY定数は、DOMツリー内のノード間の位置関係を判断する際に使用される整数値の一部です。この定数は、Dom\Node::compareDocumentPosition()メソッドの戻り値を解釈するために用いられます。compareDocumentPosition()メソッドは引数を取らず、比較対象のノードに対して、呼び出し元のノードがどのような相対位置にあるかを示すビットマスク形式の整数値を戻り値として返します。

DOCUMENT_POSITION_CONTAINED_BY定数は、呼び出し元のノードが比較対象のノードに「含まれている」（すなわち、比較対象ノードの子孫である）場合に、compareDocumentPosition()の戻り値に含まれるビットフラグです。サンプルコードでは、「grandchild」が「childA」に含まれる関係を、$grandchild->compareDocumentPosition($childA)の結果とこの定数をビット論理積（&）で比較することで検出しています。

同様に、キーワードであるDOCUMENT_POSITION_PRECEDING定数は、呼び出し元のノードが比較対象ノードよりも「前に現れる」（ドキュメント順で先にある）場合に、同じく戻り値に含まれるビットフラグです。例えば、「childA」と「childB」を比較する際に、$childA->compareDocumentPosition($childB)の結果とDOCUMENT_POSITION_PRECEDINGをビット論理積で比較し、「childA」が「childB」の前に現れる関係を判定しています。これらの定数を使用することで、DOMツリー内のノード間の複雑な位置関係を正確に特定できます。

Copy
1<?php
2
3/**
4 * Demonstrates the use of Dom\Document::DOCUMENT_POSITION_CONTAINED_BY constant.
5 *
6 * This constant is used with DOMNode::compareDocumentPosition() to check if one node
7 * is contained by another (i.e., it is a descendant).
8 */
9function demonstrateDocumentPositionContainedBy(): void
10{
11    // Create a new DOM Document instance.
12    $dom = new Dom\Document();
13
14    // Load HTML content into the document.
15    // The 'p' element is a child (and thus contained by) the 'div' element.
16    $htmlContent = '<div><p id="childNode">この段落はdiv要素の中にあります。</p></div>';
17    $dom->loadHTML($htmlContent);
18
19    // Get the potential parent node ('div') and the potential child node ('p').
20    $parentNode = $dom->getElementsByTagName('div')->item(0);
21    $childNode = $dom->getElementById('childNode');
22
23    // Proceed if both nodes are successfully found.
24    if ($parentNode && $childNode) {
25        echo "親ノード ('div') と子ノード ('p') の相対位置を比較します。\n";
26
27        // Use DOMNode::compareDocumentPosition() to determine the relationship.
28        // The method returns a bitmask that indicates various positional relationships.
29        $position = $parentNode->compareDocumentPosition($childNode);
30
31        // Check if the DOCUMENT_POSITION_CONTAINED_BY bit is set in the result.
32        // This flag indicates that the node being compared ($childNode) is contained by
33        // the reference node ($parentNode).
34        if (($position & Dom\Document::DOCUMENT_POSITION_CONTAINED_BY) === Dom\Document::DOCUMENT_POSITION_CONTAINED_BY) {
35            echo "  結果: '<p>' ノードは '<div>' ノードに包含されています。(期待通り)\n";
36        } else {
37            echo "  結果: '<p>' ノードは '<div>' ノードに包含されていません。(予期しない結果)\n";
38        }
39    } else {
40        echo "HTMLコンテンツから'div'または'p'ノードが見つかりませんでした。\n";
41    }
42
43    echo "\n--- 別の例 (包含関係にないノードとの比較) ---\n";
44
45    // Create another DOM Document with an unrelated node for comparison.
46    $anotherDom = new Dom\Document();
47    $anotherDom->loadHTML('<h1>独立した見出し</h1>');
48    $unrelatedNode = $anotherDom->getElementsByTagName('h1')->item(0);
49
50    // Compare the 'div' node from the first document with this unrelated 'h1' node.
51    if ($parentNode && $unrelatedNode) {
52        echo "親ノード ('div') と独立したノード ('h1') の相対位置を比較します。\n";
53        $position = $parentNode->compareDocumentPosition($unrelatedNode);
54
55        // Confirm that DOCUMENT_POSITION_CONTAINED_BY is NOT set for unrelated nodes.
56        if (($position & Dom\Document::DOCUMENT_POSITION_CONTAINED_BY) === Dom\Document::DOCUMENT_POSITION_CONTAINED_BY) {
57            echo "  結果: '<h1>' ノードは '<div>' ノードに包含されています。(予期しない結果)\n";
58        } else {
59            // For nodes from different documents or unrelated parts of the same document,
60            // DOCUMENT_POSITION_DISCONNECTED is typically set.
61            echo "  結果: '<h1>' ノードは '<div>' ノードに包含されていません。(期待通り)\n";
62        }
63    } else {
64        echo "比較に必要な'div'または'h1'ノードが見つかりませんでした。\n";
65    }
66}
67
68// Execute the demonstration function.
69demonstrateDocumentPositionContainedBy();

このサンプルコードは、PHPのDOM操作において、あるノードが別のノードに「包含されているか」（つまり、その子孫であるか）を判定するために使用されるDom\Document::DOCUMENT_POSITION_CONTAINED_BY定数の使い方を解説しています。この定数は、自身が特定の包含関係を示す整数値（int）を返します。

コードではまず、HTMLコンテンツを含む新しいDOMドキュメントを作成し、<div>要素とそれに含まれる<p>要素を取得しています。次に、<div>ノードに対してDOMNode::compareDocumentPosition()メソッドを呼び出し、引数に<p>ノードを渡して、両者の相対位置を比較します。このメソッドは、ノード間の様々な位置関係を示すビットマスク（複数の情報を組み合わせた整数値）を返します。

返されたビットマスクとDom\Document::DOCUMENT_POSITION_CONTAINED_BY定数をビット論理AND演算子で比較することで、<p>ノードが<div>ノードに包含されているかを判定しています。この定数との比較が真であれば、<p>ノードは<div>ノードの子孫であることが確認できます。

さらに、別の例として、関連性のない<h1>ノードと比較した場合も示されており、この場合は包含関係がないため、定数との比較が偽となることが確認できます。このように、DOCUMENT_POSITION_CONTAINED_BY定数を利用することで、DOMツリー内のノードの親子・包含関係を正確にチェックすることが可能です。