【PHP8.x】DOMAttr::DOCUMENT_POSITION_CONTAINS定数の使い方

Copy
1<?php
2
3/**
4 * DOMノードの位置関係を比較するサンプル関数。
5 * DOMNode::DOCUMENT_POSITION_CONTAINS 定数の使い方を示します。
6 *
7 * この定数はDOMNodeクラスに定義されており、compareDocumentPosition() メソッドの結果を解析するために使用されます。
8 * 提供されたリファレンス情報ではDOMAttrクラスに属するとされていますが、
9 * PHPの標準仕様（PHP 8を含む）ではDOMNodeクラスの定数として扱われます。
10 * DOMAttrクラスはDOMノードツリーの一部ではないため、compareDocumentPosition() メソッドは持ちません。
11 * しかし、DOMオブジェクト全体を理解する上で、この定数はノード間の包含関係を判断するために重要です。
12 */
13function demonstrateDomPositionComparison(): void
14{
15    // 1. DOMDocument オブジェクトを作成し、XML構造の土台とする
16    // これは、PHPでXMLやHTMLを扱う際の基本的な「ドキュメント」オブジェクトです。
17    $dom = new DOMDocument('1.0', 'UTF-8');
18    $dom->formatOutput = true; // 出力されるXMLを見やすく整形します
19
20    // 2. ルート要素 'documentRoot' を作成し、ドキュメントに追加
21    // XML/HTMLの最上位要素になります。
22    $rootElement = $dom->createElement('documentRoot');
23    $dom->appendChild($rootElement);
24
25    // 3. 子要素 'childElement' を作成し、ルート要素に追加
26    // 'documentRoot' の中に 'childElement' が含まれる構造になります。
27    $childElement = $dom->createElement('childElement');
28    $rootElement->appendChild($childElement);
29
30    // 4. 属性 'data-id' を作成 (DOMAttr オブジェクト) し、ルート要素に追加
31    // DOMAttrはXML/HTML要素の「属性」（例: <div id="myId"> の id="myId" 部分）を表します。
32    // 注意: DOMAttrはノードツリーの直接の子要素ではないため、compareDocumentPosition() メソッドは持ちません。
33    $attr = $dom->createAttribute('data-id');
34    $attr->value = 'unique_id_123';
35    $rootElement->setAttributeNode($attr);
36
37    echo "--- 生成されたXML構造 ---\n";
38    echo $dom->saveXML();
39    echo "\n";
40
41    // 5. DOMNode::compareDocumentPosition() を使用してノード間の位置を比較
42    // このメソッドは、2つのノード間の相対的な位置を示すビットマスク（数値）を返します。
43    // DOMNode::DOCUMENT_POSITION_CONTAINS は、比較対象のノードが基準ノードに「包含されている」場合にセットされるビットです。
44
45    echo "--- ノード位置の比較結果 ---\n";
46
47    // シナリオ1: 親ノードが子ノードを包含しているか？
48    // 基準ノード: $rootElement ('documentRoot')
49    // 比較対象ノード: $childElement ('childElement')
50    // 結果: 'documentRoot' は 'childElement' を包含しているため、DOCUMENT_POSITION_CONTAINS が含まれます。
51    $positionRootToChild = $rootElement->compareDocumentPosition($childElement);
52    echo "1. 'documentRoot' と 'childElement' の位置関係:\n";
53    echo "   ビットマスク値: " . $positionRootToChild . "\n";
54    if ($positionRootToChild & DOMNode::DOCUMENT_POSITION_CONTAINS) {
55        echo "   [✓] 'documentRoot' は 'childElement' を包含しています。\n";
56    } else {
57        echo "   [✗] 'documentRoot' は 'childElement' を包含していません。\n";
58    }
59    echo "\n";
60
61    // シナリオ2: 子ノードが親ノードを包含しているか？
62    // 基準ノード: $childElement ('childElement')
63    // 比較対象ノード: $rootElement ('documentRoot')
64    // 結果: 'childElement' は 'documentRoot' を包含していないため、DOCUMENT_POSITION_CONTAINS は含まれません。
65    $positionChildToRoot = $childElement->compareDocumentPosition($rootElement);
66    echo "2. 'childElement' と 'documentRoot' の位置関係:\n";
67    echo "   ビットマスク値: " . $positionChildToRoot . "\n";
68    if ($positionChildToRoot & DOMNode::DOCUMENT_POSITION_CONTAINS) {
69        echo "   [✗] 'childElement' は 'documentRoot' を包含していません。\n";
70    } else {
71        echo "   [✓] 'childElement' は 'documentRoot' を包含していません。\n";
72    }
73    echo "\n";
74
75    // シナリオ3: ドキュメント自身がルート要素を包含しているか？
76    // 基準ノード: $dom (DOMDocument オブジェクト)
77    // 比較対象ノード: $rootElement ('documentRoot')
78    // 結果: ドキュメントは常にそのルート要素を包含するため、DOCUMENT_POSITION_CONTAINS が含まれます。
79    $positionDocToRoot = $dom->compareDocumentPosition($rootElement);
80    echo "3. DOMDocument と 'documentRoot' の位置関係:\n";
81    echo "   ビットマスク値: " . $positionDocToRoot . "\n";
82    if ($positionDocToRoot & DOMNode::DOCUMENT_POSITION_CONTAINS) {
83        echo "   [✓] DOMDocument は 'documentRoot' を包含しています。\n";
84    } else {
85        echo "   [✗] DOMDocument は 'documentRoot' を包含していません。\n";
86    }
87    echo "\n";
88}
89
90// サンプル関数を実行して、動作を確認します。
91demonstrateDomPositionComparison();
92
93?>

このサンプルコードは、PHPのDOM拡張機能におけるノード間の位置関係を比較する DOMNode::DOCUMENT_POSITION_CONTAINS 定数の使い方を説明しています。この定数は、提供されたリファレンス情報では DOMAttr に属するとされていますが、PHP 8を含む標準仕様では DOMNode クラスに定義されており、DOMノードツリーにおける要素間の包含関係を判断するために用いられます。

具体的には、DOMNode::compareDocumentPosition() メソッドを使用して二つのノードを比較し、その相対的な位置関係を示すビットマスク（数値）を取得します。このメソッドは、引数として比較対象のDOMノードを受け取り、基準ノードと引数のノードが兄弟関係にあるか、包含関係にあるかといった情報を含む数値を返します。DOCUMENT_POSITION_CONTAINS 定数は、このビットマスクに含まれる特定のフラグで、基準ノードが比較対象のノードを「包含している」、つまり基準ノードが比較対象ノードの親または祖先である場合にセットされます。

サンプルコードでは、まず DOMDocument を作成し、ルート要素や子要素、属性などを追加してXML構造を構築しています。その後、DOMNode::compareDocumentPosition() メソッドを使って、親要素が子要素を包含しているか、または DOMDocument がルート要素を包含しているかといった異なるシナリオでノード間の位置を比較しています。結果は DOCUMENT_POSITION_CONTAINS 定数とのビット論理積 (&) を用いて判定され、ノードが別のノードの内部に位置するかどうかをプログラムで確認する方法を具体的に示しています。

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * DOMNode::DOCUMENT_POSITION_CONTAINS 定数の使用例を生成し、出力します。
7 *
8 * この定数は、DOMNode::compareDocumentPosition() メソッドの戻り値で使用される
9 * ビットマスクの一つで、あるノードが別のノードを含んでいるかどうかを示します。
10 *
11 * リファレンス情報に「所属クラス: DOMAttr」とありますが、DOMAttrもDOMNodeを継承しており、
12 * compareDocumentPosition() メソッドを使用できます。
13 * ただし、DOMの仕様上、要素と属性は子ノードとしての「包含関係」にはありません。
14 * このサンプルでは、要素間の包含関係と、要素と属性間の関係の両方を確認し、
15 * DOCUMENT_POSITION_CONTAINS 定数の動作を説明します。
16 *
17 * @return void
18 */
19function demonstrateDomNodePositionConstants(): void
20{
21    // 1. DOMDocumentを作成し、出力を整形
22    $dom = new DOMDocument('1.0', 'UTF-8');
23    $dom->formatOutput = true;
24
25    // 2. ルート要素を作成し、DOMに追加
26    $rootElement = $dom->createElement('root');
27    $dom->appendChild($rootElement);
28
29    // 3. 子要素を作成し、ルート要素に追加
30    $childElement = $dom->createElement('child');
31    $rootElement->appendChild($childElement);
32
33    // 4. DOMAttrを作成し、子要素に付加 (DOMAttrもDOMNodeを継承しています)
34    $attributeNode = $dom->createAttribute('id');
35    $attributeNode->value = 'child-id-value';
36    // 属性はsetAttributeNode()を使って要素に関連付けます
37    $childElement->setAttributeNode($attributeNode);
38
39    echo "--- 生成されたDOM構造 ---\n";
40    echo $dom->saveXML() . "\n";
41
42    echo "--- ノード間の位置関係の確認 ---\n";
43
44    // 5. 親要素が子要素を含んでいるかを確認
45    // DOMNode::compareDocumentPosition はビットマスクを返します。
46    $positionRootToChild = $rootElement->compareDocumentPosition($childElement);
47    echo "{$rootElement->nodeName} が {$childElement->nodeName} を含んでいるか:\n";
48    if ($positionRootToChild & DOMNode::DOCUMENT_POSITION_CONTAINS) {
49        echo "  -> はい、{$rootElement->nodeName} は {$childElement->nodeName} を含んでいます。\n";
50    } else {
51        echo "  -> いいえ、{$rootElement->nodeName} は {$childElement->nodeName} を含んでいません。\n";
52    }
53    echo "  (ビットマスク結果: " . sprintf("0x%x", $positionRootToChild) . ")\n\n";
54
55    // 6. 子要素が親要素に含められているかを確認
56    $positionChildToRoot = $childElement->compareDocumentPosition($rootElement);
57    echo "{$childElement->nodeName} が {$rootElement->nodeName} に含められているか:\n";
58    // DOCUMENT_POSITION_CONTAINED_BY は DOCUMENT_POSITION_CONTAINS の逆の関係です。
59    if ($positionChildToRoot & DOMNode::DOCUMENT_POSITION_CONTAINED_BY) {
60        echo "  -> はい、{$childElement->nodeName} は {$rootElement->nodeName} に含められています。\n";
61    } else {
62        echo "  -> いいえ、{$childElement->nodeName} は {$rootElement->nodeName} に含められていません。\n";
63    }
64    echo "  (ビットマスク結果: " . sprintf("0x%x", $positionChildToRoot) . ")\n\n";
65
66    // 7. 要素が属性を含んでいるかを確認 (リファレンス情報「DOMAttr」の文脈を考慮)
67    // DOMの仕様上、属性は要素の子ノードではないため、一般的には包含関係としては扱われません。
68    $positionElementToAttr = $childElement->compareDocumentPosition($attributeNode);
69    echo "{$childElement->nodeName} が属性 '{$attributeNode->nodeName}' を含んでいるか:\n";
70    if ($positionElementToAttr & DOMNode::DOCUMENT_POSITION_CONTAINS) {
71        echo "  -> はい、{$childElement->nodeName} は属性 '{$attributeNode->nodeName}' を含んでいます。(特殊なケース)\n";
72    } else {
73        echo "  -> いいえ、{$childElement->nodeName} は属性 '{$attributeNode->nodeName}' を含んでいません。(DOMの標準的な挙動)\n";
74    }
75    echo "  (ビットマスク結果: " . sprintf("0x%x", $positionElementToAttr) . ")\n\n";
76
77    // 8. 属性が要素に含められているかを確認
78    // 同様に、属性は要素に子ノードとして含められていないため、CONTAINED_BYは検出されません。
79    $positionAttrToElement = $attributeNode->compareDocumentPosition($childElement);
80    echo "属性 '{$attributeNode->nodeName}' が {$childElement->nodeName} に含められているか:\n";
81    if ($positionAttrToElement & DOMNode::DOCUMENT_POSITION_CONTAINED_BY) {
82        echo "  -> はい、属性 '{$attributeNode->nodeName}' は {$childElement->nodeName} に含められています。(特殊なケース)\n";
83    } else {
84        echo "  -> いいえ、属性 '{$attributeNode->nodeName}' は {$childElement->nodeName} に含められていません。(DOMの標準的な挙動)\n";
85    }
86    echo "  (ビットマスク結果: " . sprintf("0x%x", $positionAttrToElement) . ")\n\n";
87}
88
89// サンプル関数を実行
90demonstrateDomNodePositionConstants();

DOMNode::DOCUMENT_POSITION_CONTAINSは、PHPのDOM（Document Object Model）操作において、二つのノード間の相対的な位置関係を判断するための定数です。この定数は、主にDOMNode::compareDocumentPosition()メソッドの戻り値と組み合わせて使用されます。

DOMNode::compareDocumentPosition()メソッドは、比較対象のノードが基準ノードに対してどのような位置にあるかを示すビットマスク値を返します。DOCUMENT_POSITION_CONTAINS定数を用いることで、返されたビットマスク値に対して論理積（&）操作を行い、基準ノードが比較対象のノードを「含んでいる」状態にあるかを判断できます。この定数自体に引数はなく、特定の値を持ちます。

リファレンス情報ではDOMAttrクラスに所属とありますが、DOMAttrはDOMNodeを継承しているため、DOMNodeクラスで定義されているこの定数やcompareDocumentPosition()メソッドを利用できます。しかし、DOMの仕様上、要素と属性は子ノードとしての直接的な包含関係にはありません。サンプルコードでは、親要素が子要素を含む一般的なケースと、要素がその属性を含むかどうかという特殊なケースの両方を確認し、DOMにおけるノードの位置関係と、この定数の正確な動作を説明しています。この定数は、複雑なドキュメント構造をプログラムで解析・操作する際に、ノード間の親子関係や祖先・子孫関係を正確に把握するために役立ちます。