【PHP8.x】DOMCharacterData::DOCUMENT_POSITION_CONTAINED_BY定数の使い方

Copy
1<?php
2
3/**
4 * DOMNode::compareDocumentPosition() メソッドと
5 * DOM_NODE_DOCUMENT_POSITION_PRECEDING 定数の使用例を示します。
6 *
7 * この関数は、2つのDOMノード間の位置関係を比較し、
8 * 特に比較対象のノードが参照ノードに「先行している」場合に
9 * ビットマスクに含まれる DOM_NODE_DOCUMENT_POSITION_PRECEDING 定数の意味を解説します。
10 * システムエンジニアを目指す初心者にも理解しやすいよう、
11 * 具体的なHTML構造とコメントで詳細に説明します。
12 */
13function compareDomNodesPrecedingExample(): void
14{
15    // 1. DOMDocument オブジェクトを作成し、簡単なHTMLコンテンツを読み込みます。
16    $dom = new DOMDocument();
17    // HTMLのエラーを無視するために false を設定することもできますが、ここでは明示的にエラーを表示しない設定はしません。
18    // loadHTML は成功すると true を返しますが、ここでは簡潔さを優先して返り値のチェックは省略します。
19    @$dom->loadHTML('
20        <div id="wrapper">
21            <p id="nodeA">ノードA</p>
22            <span id="nodeB">ノードB</span>
23            <div id="nodeC">ノードC</div>
24        </div>
25    ');
26
27    // 2. 比較するDOMノードを取得します。
28    // id属性を使って特定のノードを簡単に取得できます。
29    $nodeA = $dom->getElementById('nodeA'); // <p id="nodeA">
30    $nodeB = $dom->getElementById('nodeB'); // <span id="nodeB">
31    $nodeC = $dom->getElementById('nodeC'); // <div id="nodeC">
32
33    // ノードが取得できなかった場合の基本的なエラーハンドリング
34    if (!$nodeA || !$nodeB || !$nodeC) {
35        echo "エラー: 必要なDOMノードが見つかりませんでした。HTML構造を確認してください。\n";
36        return;
37    }
38
39    echo "DOMNode::compareDocumentPosition() と DOM_NODE_DOCUMENT_POSITION_PRECEDING の使用例\n";
40    echo "---------------------------------------------------------------------------\n\n";
41
42    echo "処理対象のHTML構造:\n";
43    echo "  <div id=\"wrapper\">\n";
44    echo "    <p id=\"nodeA\">ノードA</p>\n";
45    echo "    <span id=\"nodeB\">ノードB</span>\n";
46    echo "    <div id=\"nodeC\">ノードC</div>\n";
47    echo "  </div>\n\n";
48
49    // --- 比較1: 参照ノード (nodeB) と 比較対象ノード (nodeA) ---
50    // HTML構造を見ると、nodeA は nodeB の前にあります。
51    echo "--- 比較1: 参照ノード ('nodeB') と 比較対象ノード ('nodeA') ---\n";
52    // compareDocumentPosition は、呼び出し元のノード（$nodeB）に対して、
53    // 引数で渡されたノード（$nodeA）がどのような位置関係にあるかを整数値（ビットマスク）で返します。
54    $position = $nodeB->compareDocumentPosition($nodeA);
55    echo "nodeB->compareDocumentPosition(nodeA) の結果 (16進数): " . sprintf("0x%02X", $position) . "\n";
56
57    // 返されたビットマスクに DOM_NODE_DOCUMENT_POSITION_PRECEDING が含まれているかを確認します。
58    // ビットAND演算子 `&` を使用して、特定のビットが立っているか（0以外の値になるか）をチェックします。
59    if (($position & DOM_NODE_DOCUMENT_POSITION_PRECEDING) !== 0) {
60        echo "  -> DOM_NODE_DOCUMENT_POSITION_PRECEDING のビットが立っています。\n";
61        echo "  これは、比較対象ノード ('nodeA') が参照ノード ('nodeB') にドキュメントツリー上で先行していることを示します。\n";
62        echo "  (実際、HTML構造を見ると 'nodeA' は 'nodeB' の前に位置しています。)\n";
63    } else {
64        echo "  -> DOM_NODE_DOCUMENT_POSITION_PRECEDING のビットは立っていません。\n";
65    }
66    echo "\n";
67
68    // --- 比較2: 参照ノード (nodeB) と 比較対象ノード (nodeC) ---
69    // HTML構造を見ると、nodeC は nodeB の後にあります。
70    echo "--- 比較2: 参照ノード ('nodeB') と 比較対象ノード ('nodeC') ---\n";
71    $position = $nodeB->compareDocumentPosition($nodeC);
72    echo "nodeB->compareDocumentPosition(nodeC) の結果 (16進数): " . sprintf("0x%02X", $position) . "\n";
73
74    if (($position & DOM_NODE_DOCUMENT_POSITION_PRECEDING) !== 0) {
75        echo "  -> DOM_NODE_DOCUMENT_POSITION_PRECEDING のビットが立っています。\n";
76    } else {
77        echo "  -> DOM_NODE_DOCUMENT_POSITION_PRECEDING のビットは立っていません。\n";
78        echo "  これは、比較対象ノード ('nodeC') が参照ノード ('nodeB') にドキュメントツリー上で先行していないことを示します。\n";
79        echo "  (実際、HTML構造を見ると 'nodeC' は 'nodeB' の後に位置しています。)\n";
80    }
81    echo "\n";
82
83    // --- 比較3: 参照ノード (nodeA) と 比較対象ノード (nodeA) ---
84    // 同じノード同士の比較
85    echo "--- 比較3: 参照ノード ('nodeA') と 比較対象ノード ('nodeA') ---\n";
86    $position = $nodeA->compareDocumentPosition($nodeA);
87    echo "nodeA->compareDocumentPosition(nodeA) の結果 (16進数): " . sprintf("0x%02X", $position) . "\n";
88
89    if (($position & DOM_NODE_DOCUMENT_POSITION_PRECEDING) !== 0) {
90        echo "  -> DOM_NODE_DOCUMENT_POSITION_PRECEDING のビットが立っています。\n";
91    } else {
92        echo "  -> DOM_NODE_DOCUMENT_POSITION_PRECEDING のビットは立っていません。\n";
93        echo "  同じノード同士の比較では、通常、このビットは立ちません。\n";
94        echo "  結果が 0x00 の場合、両方のノードが同じであることを示します。\n";
95    }
96    echo "\n";
97}
98
99// 関数を実行して、上記の説明と結果を表示します。
100compareDomNodesPrecedingExample();

このコードは、PHPのDOM拡張機能を使って、HTML文書内の2つのノードが互いにどのような位置関係にあるかを調べる方法を示します。具体的には、DOMNode::compareDocumentPosition() メソッドと DOM_NODE_DOCUMENT_POSITION_PRECEDING 定数の使用例です。

DOMNode::compareDocumentPosition() メソッドは、呼び出し元のノード（参照ノード）に対する引数で指定されたノード（比較対象ノード）の位置関係を、ビットの組み合わせで表現された整数値（ビットマスク）として返します。この戻り値は int 型です。

DOM_NODE_DOCUMENT_POSITION_PRECEDING 定数は、このビットマスクに含まれる値の一つで、比較対象ノードが参照ノードよりもドキュメントツリー上で「先行している」（物理的に前に位置している）場合に、そのビットが結果としてセットされます。この定数自体は引数を取りません。

サンプルコードでは、まず簡単なHTML構造からDOMドキュメントを作成し、getElementById() メソッドで特定のノードを取得します。その後、これらのノードを複数組み合わせて compareDocumentPosition() メソッドを呼び出し、返された結果と DOM_NODE_DOCUMENT_POSITION_PRECEDING 定数をビットAND演算子 (&) で比較することで、比較対象ノードが先行しているかどうかを判定し、その結果を画面に出力しています。この比較により、HTML要素の並び順をプログラムで把握する基本的な方法を学べます。

Copy
1<?php
2
3/**
4 * DOMノード間の位置関係を比較し、DOCUMENT_POSITION_CONTAINED_BY 定数の使用方法を示すサンプルコードです。
5 *
6 * DOMNode::compareDocumentPosition() メソッドは、二つのノード間の相対的な位置関係を
7 * ビットマスクの整数値で返します。DOCUMENT_POSITION_CONTAINED_BY 定数は、
8 * 比較対象のノード（引数で渡されたノード）が、メソッドを呼び出したノードに「含まれている」
9 * （つまり、呼び出し元のノードが引数のノードの子孫である）場合にセットされるビットです。
10 */
11function demonstrateDocumentPositionContainedBy(): void
12{
13    // DOMDocument オブジェクトを作成し、シンプルなHTML構造をロード
14    $dom = new DOMDocument();
15    // HTMLのパースエラーを抑制するため、@ を使用
16    @$dom->loadHTML('<body><div id="parent"><p id="child">Hello World</p></div></body>');
17
18    // 親ノードと子ノードをIDで取得
19    $parentNode = $dom->getElementById('parent');
20    $childNode = $dom->getElementById('child');
21
22    // ノードが取得できなかった場合のチェック
23    if (!$parentNode || !$childNode) {
24        echo "エラー: 指定されたIDのノードが見つかりませんでした。\n";
25        return;
26    }
27
28    echo "--- DOMノード間の位置関係の比較 ---\n\n";
29
30    // ケース1: 子ノードが親ノードに「含まれている」かを確認
31    // `$childNode` (p要素) から `$parentNode` (div要素) を比較します。
32    // この場合、「$childNode は $parentNode に含まれている」関係にあります。
33    // つまり、$childNode が $parentNode の子孫であるため、DOCUMENT_POSITION_CONTAINED_BY がセットされます。
34    $positionChildToParent = $childNode->compareDocumentPosition($parentNode);
35
36    echo "比較元: <p id=\"child\"> ノード\n";
37    echo "比較先: <div id=\"parent\"> ノード\n";
38    echo "compareDocumentPosition() の戻り値: " . $positionChildToParent . "\n";
39
40    // DOCUMENT_POSITION_CONTAINED_BY がセットされているかチェック
41    // DOMNode::DOCUMENT_POSITION_CONTAINED_BY は、DOMNode クラスで定義されている定数です。
42    // DOMCharacterData も DOMNode を継承しているため、この定数にアクセスできます。
43    if ($positionChildToParent & DOMNode::DOCUMENT_POSITION_CONTAINED_BY) {
44        echo "- 結果: <p id=\"child\"> は <div id=\"parent\"> に含まれています。\n";
45    } else {
46        echo "- 結果: <p id=\"child\"> は <div id=\"parent\"> に含まれていません。\n";
47    }
48    echo "\n";
49
50    // ケース2: 親ノードが子ノードを「含んでいる」かを確認
51    // `$parentNode` (div要素) から `$childNode` (p要素) を比較します。
52    // この場合、「$parentNode は $childNode を含んでいる」関係にあります。
53    // DOCUMENT_POSITION_CONTAINED_BY ではなく、DOCUMENT_POSITION_CONTAINS がセットされます。
54    $positionParentToChild = $parentNode->compareDocumentPosition($childNode);
55
56    echo "比較元: <div id=\"parent\"> ノード\n";
57    echo "比較先: <p id=\"child\"> ノード\n";
58    echo "compareDocumentPosition() の戻り値: " . $positionParentToChild . "\n";
59
60    // DOCUMENT_POSITION_CONTAINED_BY がセットされているかチェック (この場合はセットされない)
61    if ($positionParentToChild & DOMNode::DOCUMENT_POSITION_CONTAINED_BY) {
62        echo "- 結果: <div id=\"parent\"> は <p id=\"child\"> に含まれています。\n";
63    } else {
64        echo "- 結果: <div id=\"parent\"> は <p id=\"child\"> に含まれていません。\n";
65    }
66
67    // 参考: DOCUMENT_POSITION_CONTAINS がセットされているかチェック (この場合はセットされる)
68    if ($positionParentToChild & DOMNode::DOCUMENT_POSITION_CONTAINS) {
69        echo "- 参考: <div id=\"parent\"> は <p id=\"child\"> を含んでいます。\n";
70    }
71    echo "\n";
72}
73
74// 関数を実行して、DOMノードの位置関係の比較結果を表示
75demonstrateDocumentPositionContainedBy();
76
77?>

PHP 8のDOCUMENT_POSITION_CONTAINED_BY定数は、DOM（Document Object Model）ノード間の位置関係を識別するための整数値です。この定数自体に引数はなく、常に整数型の値を返します。主にDOMNode::compareDocumentPosition()メソッドの戻り値を評価する際に利用されますが、DOMCharacterDataを含むDOMNodeを継承するクラスからアクセス可能です。

DOMNode::compareDocumentPosition()メソッドは、メソッドを呼び出したノードと引数で渡されたノードの相対的な位置関係を示すビットマスク（整数の組み合わせ）を返します。この戻り値にDOCUMENT_POSITION_CONTAINED_BYが含まれている場合、それは「引数で渡されたノードが、メソッドを呼び出したノードに含まれている（すなわち、呼び出し元のノードが引数のノードの子孫である）」という関係を示します。

サンプルコードでは、子ノード（<p id="child">）から親ノード（<div id="parent">）を比較しています。この場合、子ノードが親ノードの子孫であるため、compareDocumentPosition()の戻り値にはDOCUMENT_POSITION_CONTAINED_BYがセットされ、子ノードが親ノードに含まれると判断されます。逆に親ノードから子ノードを比較する際は、DOCUMENT_POSITION_CONTAINED_BYではなく、DOCUMENT_POSITION_CONTAINSがセットされ、親ノードが子ノードを含んでいるという異なる関係を示します。この定数を用いることで、DOMツリー内でのノードの包含関係を正確に判定できます。