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

Copy
1<?php
2
3/**
4 * DOMノード間の位置関係を比較し、特定のノードが別のノードを含むか判定するサンプル関数。
5 *
6 * システムエンジニアを目指す初心者向けに、PHPのDOMツリーの基本と、
7 * Dom\CharacterData::DOCUMENT_POSITION_CONTAINS 定数の具体的な使い方を示します。
8 * この定数は、DOMノード間の相対位置を示すビットマスクの一部であり、
9 * あるノードが別のノードの子孫であるかどうかを判定するために使用されます。
10 */
11function demonstrateDomNodePositionComparison(): void
12{
13    // 1. 新しいDOMドキュメントを作成します。
14    // \DOMDocument は、XMLやHTMLドキュメントをプログラムで操作するためのクラスです。
15    $document = new \DOMDocument();
16    $document->formatOutput = true; // 出力されるXMLを見やすくするための設定
17
18    // 2. ルート要素（親ノード）を作成し、ドキュメントに追加します。
19    $rootElement = $document->createElement('container');
20    $document->appendChild($rootElement);
21
22    // 3. 子要素を作成し、ルート要素に追加します。
23    $childElement = $document->createElement('item');
24    $rootElement->appendChild($childElement);
25
26    // 4. テキストノードを作成し、子要素に追加します。
27    // テキストノード (\DOMText) は、Dom\CharacterData インターフェースを実装するノードの一種です。
28    $textNode = $document->createTextNode('Content here.');
29    $childElement->appendChild($textNode);
30
31    echo "--- 生成されたDOMツリー ---\n";
32    echo $document->saveXML() . "\n";
33    echo "--------------------------\n\n";
34
35    echo "--- ノードの位置関係比較のデモンストレーション ---\n";
36
37    // 比較対象のノードを明確にします。
38    // $rootElement: <container>...</container>
39    // $childElement: <item>...</item> (rootElementの子)
40    // $textNode: "Content here." (childElementの子)
41
42    // Case 1: 親ノードが子ノードを含むか？ (rootElement と childElement)
43    // compareDocumentPosition() メソッドは、呼び出し元のノードと引数で渡されたノードの
44    // 相対的な位置関係を示す整数値（ビットマスク）を返します。
45    $positionRootChild = $rootElement->compareDocumentPosition($childElement);
46
47    echo "1. rootElement (<container>) と childElement (<item>) の比較:\n";
48    echo "   compareDocumentPosition() の生の値: " . $positionRootChild . "\n";
49
50    // Dom\CharacterData::DOCUMENT_POSITION_CONTAINS 定数を使って、
51    // $rootElement が $childElement を含んでいるか確認します。
52    // 結果のビットマスクと定数をビット論理積演算子 (&) で比較し、
53    // 特定のビットが立っている（関係がある）かを判定します。
54    if (($positionRootChild & \Dom\CharacterData::DOCUMENT_POSITION_CONTAINS) === \Dom\CharacterData::DOCUMENT_POSITION_CONTAINS) {
55        echo "   判定結果: rootElement は childElement を含んでいます。\n";
56    } else {
57        echo "   判定結果: rootElement は childElement を含んでいません。\n";
58    }
59    echo "\n";
60
61    // Case 2: 子ノードが親ノードに含まれるか？ (childElement と rootElement)
62    // (ここでは CONTAINS 定数を使って、逆の関係を確認します)
63    $positionChildRoot = $childElement->compareDocumentPosition($rootElement);
64
65    echo "2. childElement (<item>) と rootElement (<container>) の比較:\n";
66    echo "   compareDocumentPosition() の生の値: " . $positionChildRoot . "\n";
67
68    if (($positionChildRoot & \Dom\CharacterData::DOCUMENT_POSITION_CONTAINS) === \Dom\CharacterData::DOCUMENT_POSITION_CONTAINS) {
69        echo "   判定結果: childElement は rootElement を含んでいます。(これは誤りです)\n";
70    } else {
71        // この場合は、DOCUMENT_POSITION_CONTAINED_BY のビットが立つはずです。
72        echo "   判定結果: childElement は rootElement を含んでいません。(正しい)\n";
73    }
74    echo "\n";
75
76    // Case 3: ルート要素がテキストノードを含むか？ (rootElement と textNode)
77    // テキストノードもDOMツリーの一部であり、親ノードとの包含関係を確認できます。
78    $positionRootText = $rootElement->compareDocumentPosition($textNode);
79
80    echo "3. rootElement (<container>) と textNode (\"Content here.\") の比較:\n";
81    echo "   compareDocumentPosition() の生の値: " . $positionRootText . "\n";
82
83    if (($positionRootText & \Dom\CharacterData::DOCUMENT_POSITION_CONTAINS) === \Dom\CharacterData::DOCUMENT_POSITION_CONTAINS) {
84        echo "   判定結果: rootElement は textNode を含んでいます。\n";
85    } else {
86        echo "   判定結果: rootElement は textNode を含んでいません。\n";
87    }
88    echo "\n";
89}
90
91// 上記のデモンストレーション関数を実行します。
92demonstrateDomNodePositionComparison();

このPHPコードは、ウェブページの構造を表すDOM（Document Object Model）ツリーにおけるノード間の位置関係、特に「あるノードが別のノードを含むか」を判定する方法をデモンストレーションします。まず、\DOMDocumentクラスを使用して、<container>、<item>、そしてテキストノードを含むシンプルなDOMツリーをプログラム的に構築します。

ノード間の位置関係を調べるには、compareDocumentPosition()メソッドを使用します。このメソッドは、呼び出し元のノードと引数に渡されたノードの相対的な位置を示す整数値（ビットマスク）を返します。この戻り値は複数の情報を含んでおり、特定の関係を抽出するためにPHPの定数とビット論理積演算子を利用します。

ここで中心となるのが、Dom\CharacterData::DOCUMENT_POSITION_CONTAINS定数です。この定数は整数型で、compareDocumentPosition()メソッドの戻り値に含まれるビットの一つとして、「呼び出し元のノードが引数で渡されたノードを含んでいる」という関係を示します。サンプルコードでは、$rootElementが$childElementを、また$childElementが$textNodeを含むといった、親と子の関係をこの定数を使って確認しています。具体的には、compareDocumentPosition()の戻り値とDom\CharacterData::DOCUMENT_POSITION_CONTAINS定数をビット論理積演算子&で比較し、その結果が定数と完全に一致するかどうかで、包含関係の有無を正確に判定しています。これにより、DOMツリー内で要素がどのように階層的に配置されているかをプログラムで理解し、操作する基礎的なスキルを習得できます。

Copy
1<?php
2
3use Dom\DOMDocument; // For PHP 8 DOM classes
4use DOMNode;        // For the DOMNode class, which defines DOCUMENT_POSITION_* constants
5
6/**
7 * Demonstrates the usage of the DOCUMENT_POSITION_CONTAINS constant.
8 *
9 * This constant is an integer bitmask that indicates whether one DOM node
10 * contains another when comparing their positions in a document. It's typically
11 * used with the `DOMNode::compareDocumentPosition()` method.
12 */
13function demonstrateDocumentPositionContains(): void
14{
15    // Create a new DOM document with a simple structure
16    $dom = new DOMDocument();
17    $dom->loadXML('<root><parent><child/></parent></root>');
18
19    // Retrieve specific nodes from the document
20    $rootNode = $dom->documentElement;      // Represents the <root> element
21    $parentNode = $rootNode->firstChild;    // Represents the <parent> element
22    $childNode = $parentNode->firstChild;   // Represents the <child> element
23
24    // Verify that all required nodes were successfully loaded
25    if (!$rootNode || !$parentNode || !$childNode) {
26        echo "Error: Failed to load or find expected nodes in the DOM structure.\n";
27        return;
28    }
29
30    // --- Scenario 1: Parent node contains child node ---
31    // Compare the parent node against its child node.
32    // The `compareDocumentPosition` method returns a bitmask representing the relationship.
33    $positionResult = $parentNode->compareDocumentPosition($childNode);
34
35    // Check if the result includes the DOMNode::DOCUMENT_POSITION_CONTAINS flag.
36    // This constant is an integer value (a bit) that signifies the 'contains' relationship.
37    // We use a bitwise AND operator (`&`) to check if this specific bit is set.
38    if (($positionResult & DOMNode::DOCUMENT_POSITION_CONTAINS) === DOMNode::DOCUMENT_POSITION_CONTAINS) {
39        echo "Output for Scenario 1: The 'parent' node CONTAINS the 'child' node. (Expected: Yes)\n";
40    } else {
41        echo "Output for Scenario 1: The 'parent' node does NOT contain the 'child' node. (Expected: No)\n";
42    }
43
44    // --- Scenario 2: Child node does not contain parent node ---
45    // Compare the child node against its parent node.
46    // In this case, the child node should not contain the parent node.
47    $inversePositionResult = $childNode->compareDocumentPosition($parentNode);
48
49    // Check for the DOCUMENT_POSITION_CONTAINS flag again for the inverse relationship.
50    if (($inversePositionResult & DOMNode::DOCUMENT_POSITION_CONTAINS) === DOMNode::DOCUMENT_POSITION_CONTAINS) {
51        echo "Output for Scenario 2: The 'child' node CONTAINS the 'parent' node. (Expected: No)\n";
52    } else {
53        echo "Output for Scenario 2: The 'child' node does NOT contain the 'parent' node. (Expected: Yes)\n";
54    }
55}
56
57// Execute the demonstration function
58demonstrateDocumentPositionContains();

DOCUMENT_POSITION_CONTAINSは、PHPにおけるDOM（Document Object Model）操作で、2つのノード（HTMLやXMLの要素やテキストなど）が互いにどのような包含関係にあるかを判定するための整数型の定数です。この定数自体に引数はなく、戻り値として整数値（int）を持ちます。主に、DOMNodeクラスのcompareDocumentPosition()メソッドが返す結果と組み合わせて使用されます。

compareDocumentPosition()メソッドは、比較対象のノード間の位置関係を示す複数の情報がビットとして結合された整数値（ビットマスク）を返します。DOCUMENT_POSITION_CONTAINS定数は、そのビットマスクの中に、一方のノードがもう一方のノードを「含んでいる」という情報が含まれているかどうかを確認するために利用されます。具体的には、compareDocumentPosition()の戻り値とDOCUMENT_POSITION_CONTAINSをビットAND演算子（&）で比較し、同じ値になれば包含関係が成立していると判断できます。

サンプルコードでは、まず<root><parent><child/></parent></root>というXML構造を作成し、各要素をノードとして取得しています。最初のシナリオでは、<parent>ノードが<child>ノードを含む関係にあるかを確認します。$parentNode->compareDocumentPosition($childNode)の結果をDOMNode::DOCUMENT_POSITION_CONTAINSと比較することで、<parent>が<child>を含んでいることが正しく判定されます。次に、<child>ノードが<parent>ノードを含むかを確認する逆のシナリオでは、同様の比較を行い、<child>が<parent>を含んでいないことが判定されます。このように、この定数を用いることで、DOMツリー内でのノード間の親子関係や包含関係をプログラムで正確に判断することが可能になります。