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

Copy
1<?php
2
3/**
4 * Dom\Document::DOCUMENT_POSITION_CONTAINS 定数の使用例を示します。
5 *
6 * この定数は、DOM (Document Object Model) のノード間の位置関係を示す定数の一つです。
7 * 特に、Dom\Node::compareDocumentPosition() メソッドの戻り値として利用されるビットマスクの一部であり、
8 * あるノードが別のノードを「包含している」場合に、このビットが設定されます。
9 *
10 * システムエンジニアを目指す初心者の方へ:
11 * DOMはHTMLやXMLドキュメントの構造を表すプログラミングインターフェースです。
12 * ここでは、ドキュメント内の要素が互いにどのような親子関係や兄弟関係にあるかを
13 * プログラムで判別する方法を学びます。
14 */
15function demonstrateDomDocumentPositionContains(): void
16{
17    // 1. Dom\Document オブジェクトの作成
18    // これは新しいXMLドキュメントを作成するための基盤となります。
19    // PHP 8 では、名前空間つきの Dom\Document クラスが推奨されます。
20    $dom = new Dom\Document('1.0', 'UTF-8');
21    // 出力されるXMLを見やすくするために整形を有効にします。
22    $dom->formatOutput = true;
23
24    // 2. DOMノード（要素）の作成と追加
25    // 'parent' という名前の要素を作成し、ドキュメントのルート要素として追加します。
26    $parentElement = $dom->createElement('parent');
27    $dom->appendChild($parentElement);
28
29    // 'child' という名前の要素を作成し、'parent' 要素の子要素として追加します。
30    $childElement = $dom->createElement('child');
31    $parentElement->appendChild($childElement);
32
33    echo "--- Dom\\Document::DOCUMENT_POSITION_CONTAINS 定数の動作確認 ---\n\n";
34
35    // 3. ノード間の位置関係の比較 (ケース1: 親が子を包含)
36    // $parentElement が $childElement を包含しているかを確認します。
37    // compareDocumentPosition() メソッドは、2つのノード間の位置関係を示す
38    // ビットマスク（複数の情報をまとめた数値）を返します。
39    $positionFromParent = $parentElement->compareDocumentPosition($childElement);
40
41    echo "比較対象: parentElement (呼び出し元) と childElement (引数)\n";
42    echo "  compareDocumentPosition() の戻り値 (ビットマスク): " . $positionFromParent . "\n";
43    echo "  Dom\\Document::DOCUMENT_POSITION_CONTAINS 定数の値: " . Dom\Document::DOCUMENT_POSITION_CONTAINS . "\n";
44
45    // 戻り値のビットマスクと Dom\Document::DOCUMENT_POSITION_CONTAINS 定数を
46    // ビット論理積演算子 (&) を使って比較します。
47    // これにより、戻り値のビットマスクの中に DOCUMENT_POSITION_CONTAINS が含まれているかを確認できます。
48    if (($positionFromParent & Dom\Document::DOCUMENT_POSITION_CONTAINS) === Dom\Document::DOCUMENT_POSITION_CONTAINS) {
49        echo "  結果: はい、'parentElement' は 'childElement' を包含しています。\n";
50    } else {
51        echo "  結果: いいえ、'parentElement' は 'childElement' を包含していません。\n";
52    }
53    echo "\n";
54
55    // 4. ノード間の位置関係の比較 (ケース2: 子が親を包含していない)
56    // $childElement が $parentElement を包含しているかを確認します。
57    // 通常、子要素が親要素を包含することはありません。
58    $positionFromChild = $childElement->compareDocumentPosition($parentElement);
59
60    echo "比較対象: childElement (呼び出し元) と parentElement (引数)\n";
61    echo "  compareDocumentPosition() の戻り値 (ビットマスク): " . $positionFromChild . "\n";
62    echo "  Dom\\Document::DOCUMENT_POSITION_CONTAINS 定数の値: " . Dom\Document::DOCUMENT_POSITION_CONTAINS . "\n";
63    // 参考: 逆の包含関係を示す定数 Dom\Document::DOCUMENT_POSITION_CONTAINED_BY
64    echo "  Dom\\Document::DOCUMENT_POSITION_CONTAINED_BY 定数の値 (参考): " . Dom\Document::DOCUMENT_POSITION_CONTAINED_BY . "\n";
65
66    if (($positionFromChild & Dom\Document::DOCUMENT_POSITION_CONTAINS) === Dom\Document::DOCUMENT_POSITION_CONTAINS) {
67        echo "  結果: はい、'childElement' は 'parentElement' を包含しています。\n";
68    } else {
69        echo "  結果: いいえ、'childElement' は 'parentElement' を包含していません。\n";
70    }
71
72    // 補足として、子要素が親要素に「包含されている」かの確認も行います。
73    if (($positionFromChild & Dom\Document::DOCUMENT_POSITION_CONTAINED_BY) === Dom\Document::DOCUMENT_POSITION_CONTAINED_BY) {
74        echo "  補足: しかし、'childElement' は 'parentElement' に包含されています (DOCUMENT_POSITION_CONTAINED_BY のビットが立っています)。\n";
75    }
76    echo "\n";
77}
78
79// デモンストレーション関数を実行します。
80demonstrateDomDocumentPositionContains();

PHPのDom\Document::DOCUMENT_POSITION_CONTAINS 定数は、DOM（Document Object Model）でHTMLやXMLドキュメントのノード（要素など）間の位置関係をプログラムで判別する際に用いられる整数値の定数です。具体的には、「あるノードが別のノードを包含しているか」を示すビットマスクの一部として機能します。

この定数は、Dom\Node::compareDocumentPosition() メソッドの戻り値と組み合わせて使用されます。compareDocumentPosition() メソッドは、比較対象となる二つのノード間の相対的な位置関係を、複数の情報をまとめたビットマスク（整数値）として返します。この戻り値のビットマスクに DOCUMENT_POSITION_CONTAINS 定数のビットが含まれている場合、メソッドの呼び出し元となったノードが、引数で渡されたノードを内包している（例えば親要素である）ことを意味します。

サンプルコードでは、まず新しいDOMドキュメントと、そこに「parent」要素と「child」要素を親子関係として作成しています。そして、parentElement->compareDocumentPosition($childElement) を実行して親要素が子要素を包含しているかを、またその逆のケースとして childElement->compareDocumentPosition($parentElement) を実行して子が親を包含しているかを確認しています。結果の判定は、戻り値のビットマスクと DOCUMENT_POSITION_CONTAINS 定数をビット論理積演算子 (&) で比較することで行われ、DOMツリーにおけるノードの包含関係を正確に検出する方法を示しています。

Copy
1<?php
2
3/**
4 * DOMノードの比較機能とDom\Node::DOCUMENT_POSITION_CONTAINS定数の使用例を示します。
5 *
6 * この定数は、PHPのDOM拡張機能の一部であり、Dom\Node::compareDocumentPosition() メソッドの
7 * 結果を解釈するために使用されます。
8 * Dom\Node::DOCUMENT_POSITION_CONTAINS は、参照ノードが比較対象のノードを
9 * 含んでいる場合に結果のビットマスクに含まれる整数定数です。
10 * (注: 提供されたリファレンス情報では「所属クラス: Dom\Document」とありますが、
11 *      この定数はDom\Nodeクラスで定義され、継承または直接アクセスされます。)
12 */
13function demonstrateDomNodeComparison(): void
14{
15    // 1. 新しいDOMドキュメントを作成します
16    $document = new Dom\Document('1.0', 'UTF-8');
17    $document->formatOutput = true; // 出力を整形して見やすくします
18
19    // 2. ルート要素を作成し、ドキュメントに追加します
20    $rootElement = $document->createElement('root');
21    $document->appendChild($rootElement);
22
23    // 3. 親要素を作成し、ルート要素に追加します
24    $parentElement = $document->createElement('parent');
25    $rootElement->appendChild($parentElement);
26
27    // 4. 子要素を作成し、親要素に追加します
28    $childElement = $document->createElement('child');
29    $parentElement->appendChild($childElement);
30
31    echo "--- Dom\\Node::compareDocumentPosition() の使用例 ---\n\n";
32
33    // シナリオ1: 親ノードと子ノードを比較
34    // parentElement は childElement を含んでいるため、DOCUMENT_POSITION_CONTAINS が含まれるはずです。
35    echo "シナリオ1: parentElement と childElement の比較\n";
36    $position1 = $parentElement->compareDocumentPosition($childElement);
37    echo "  比較結果の数値: " . $position1 . "\n";
38
39    // Dom\Node::DOCUMENT_POSITION_CONTAINS (int) は、参照ノードが比較対象ノードを含んでいることを示します。
40    // この定数はDom\Nodeクラスで定義されており、その値は整数です。
41    echo "  Dom\\Node::DOCUMENT_POSITION_CONTAINS の値: " . Dom\Node::DOCUMENT_POSITION_CONTAINS . "\n";
42
43    // compareDocumentPosition() の結果はビットマスクなので、
44    // ビット論理AND演算子 (&) を使用して特定の定数（ビット）が含まれているかを確認します。
45    if (($position1 & Dom\Node::DOCUMENT_POSITION_CONTAINS) === Dom\Node::DOCUMENT_POSITION_CONTAINS) {
46        echo "  結果: parentElement は childElement を含んでいます。\n";
47    } else {
48        echo "  結果: parentElement は childElement を含んでいません。\n";
49    }
50    echo "\n";
51
52    // シナリオ2: 子ノードと親ノードを比較
53    // childElement は parentElement を含んでいません。(むしろ childElement が parentElement に含まれています)
54    echo "シナリオ2: childElement と parentElement の比較\n";
55    $position2 = $childElement->compareDocumentPosition($parentElement);
56    echo "  比較結果の数値: " . $position2 . "\n";
57
58    if (($position2 & Dom\Node::DOCUMENT_POSITION_CONTAINS) === Dom\Node::DOCUMENT_POSITION_CONTAINS) {
59        echo "  結果: childElement は parentElement を含んでいます。\n";
60    } else {
61        echo "  結果: childElement は parentElement を含んでいません。\n";
62        echo "  (この場合、childElement が parentElement に含まれているため、\n";
63        echo "   比較の参照元が「含まれる側」であるため、DOCUMENT_POSITION_CONTAINS は立ちません。\n";
64        echo "   結果には通常、Dom\\Node::DOCUMENT_POSITION_PRECEDING などが含まれます。)\n";
65    }
66    echo "\n";
67
68    // シナリオ3: 異なる枝のノードを比較
69    // 新しい兄弟要素を作成します
70    $siblingElement = $document->createElement('sibling');
71    $rootElement->appendChild($siblingElement);
72
73    echo "シナリオ3: parentElement と siblingElement の比較 (同じ階層で異なるノード)\n";
74    $position3 = $parentElement->compareDocumentPosition($siblingElement);
75    echo "  比較結果の数値: " . $position3 . "\n";
76
77    if (($position3 & Dom\Node::DOCUMENT_POSITION_CONTAINS) === Dom\Node::DOCUMENT_POSITION_CONTAINS) {
78        echo "  結果: parentElement は siblingElement を含んでいます。\n";
79    } else {
80        echo "  結果: parentElement は siblingElement を含んでいません。\n";
81        // ここでは通常、Dom\Node::DOCUMENT_POSITION_FOLLOWING (後続) または
82        // Dom\Node::DOCUMENT_POSITION_PRECEDING (先行) が期待されます。
83    }
84}
85
86// 関数の実行
87demonstrateDomNodeComparison();

PHPのDom\Node::DOCUMENT_POSITION_CONTAINSは、XMLやHTMLドキュメントの構造を操作するDOM拡張機能で利用される整数定数です。この定数はDom\Nodeクラスに属しており、引数はなく、定数そのものが整数値（int）を保持しています。主にDom\Node::compareDocumentPosition()メソッドの戻り値を解析する際に活用されます。

compareDocumentPosition()メソッドは、2つのDOMノード間の相対的な位置関係を示すビットマスク（複数の状態を組み合わせた数値）を返します。この戻り値とDom\Node::DOCUMENT_POSITION_CONTAINS定数をビット論理AND演算子（&）で組み合わせることで、基準となるノードが比較対象のノードを子孫として含んでいるかどうかを正確に判断することができます。

サンプルコードでは、まずDOMドキュメントを作成し、「root」「parent」「child」という階層的な要素を構築しています。$parentElement->compareDocumentPosition($childElement)のように親ノードと子ノードを比較すると、親ノードが子ノードを含んでいるため、結果のビットマスクにDOCUMENT_POSITION_CONTAINSが含まれます。これにより、「parentElement は childElement を含んでいます」と表示されます。一方、子ノードが親ノードを含んでいるかを比較したり、異なる階層のノード同士を比較したりした場合は、この定数は結果に含まれず、異なる位置関係が示されます。このように、この定数はDOMツリーにおけるノードの包含関係をプログラムで効率的に確認するために重要な役割を果たします。