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

Copy
1<?php
2
3use Dom\Document;
4use Dom\Node; // Dom\Node クラスの定数を使用するため
5
6/**
7 * DOMノード間の位置関係を比較するデモンストレーション関数です。
8 * Dom\CharacterData::DOCUMENT_POSITION_CONTAINED_BY 定数（Dom\Nodeから継承）と
9 * キーワードに関連する DOCUMENT_POSITION_PRECEDING 定数に焦点を当てます。
10 *
11 * compareDocumentPosition() メソッドは、2つのノード間の相対的な位置関係を示すビットマスクを返します。
12 * 返される値は、複数の定数の組み合わせである可能性があります。
13 */
14function demonstrateNodePositionComparison(): void
15{
16    // 新しいDOMドキュメントを作成し、サンプルXMLをロードします。
17    // PHP 8の新しいDom拡張では、クラスは 'Dom\' 名前空間に属します。
18    $document = new Document();
19    $document->loadXML(
20        '<div>
21            <p id="p1">これは<b>太字</b>のテキストです。</p>
22            <p id="p2">別の段落です。</p>
23         </div>'
24    );
25
26    // 比較対象となるノードを取得します。
27    // getElementsByTagName() や getElementById() は Dom\Element のインスタンスを返します。
28    $div = $document->getElementsByTagName('div')->item(0); // <div> 要素
29    $p1 = $document->getElementById('p1');                   // <p id="p1"> 要素
30    $b = $document->getElementsByTagName('b')->item(0);     // <b> 要素
31
32    // Dom\CharacterData の子孫である Dom\Text ノードを取得します。
33    // Dom\CharacterData はテキストノードやコメントノードなどの抽象的な基底クラスです。
34    // $p1_text_node_child は <p id="p1"> の最初の子ノードであるテキストノード "これは"
35    $p1_text_node_child = $p1->firstChild; // Dom\Text のインスタンス
36    // $b_text_node_child は <b> の最初の子ノードであるテキストノード "太字"
37    $b_text_node_child = $b->firstChild;   // Dom\Text のインスタンス
38
39    echo "=== DOMノード位置の比較例 ===\n\n";
40
41    // --- 例1: Dom\CharacterData::DOCUMENT_POSITION_CONTAINED_BY の使用 ---
42    // '太字' テキストノード ($b_text_node_child) が親要素 ($b) に含まれるかを確認します。
43    // Dom\Text は Dom\CharacterData を継承しており、compareDocumentPosition() メソッドを使用できます。
44    echo "--- '太字' テキストノードと 'b' 要素の比較 ('太字' Text vs 'b' Element) ---\n";
45    $result_b_text_b_element = $b_text_node_child->compareDocumentPosition($b);
46
47    if ($result_b_text_b_element & Node::DOCUMENT_POSITION_CONTAINED_BY) {
48        // DOCUMENT_POSITION_CONTAINED_BY は Dom\Node クラスで定義されていますが、
49        // Dom\CharacterData（およびその子孫クラス）からもアクセス可能です。
50        echo "  結果: '太字' テキストノードは 'b' 要素に含まれています。\n";
51        echo "  (返されたフラグが " . Node::DOCUMENT_POSITION_CONTAINED_BY . " に該当)\n";
52    } else {
53        echo "  結果: '太字' テキストノードは 'b' 要素に含まれていません。\n";
54    }
55    echo "\n";
56
57    // --- 例2: キーワード 'document_position_preceding' に関連する定数の使用 ---
58    // 'これは' テキストノード ($p1_text_node_child) が
59    // '太字' テキストノード ($b_text_node_child) に先行するかを確認します。
60    // DOMツリー上の文書順で比較されます。
61    echo "--- 'これは' テキストノードと '太字' テキストノードの比較 ('これは' Text vs '太字' Text) ---\n";
62    $result_p1_text_b_text = $p1_text_node_child->compareDocumentPosition($b_text_node_child);
63
64    if ($result_p1_text_b_text & Node::DOCUMENT_POSITION_PRECEDING) {
65        echo "  結果: 'これは' テキストノードは '太字' テキストノードに先行しています。\n";
66        echo "  (返されたフラグが " . Node::DOCUMENT_POSITION_PRECEDING . " に該当)\n";
67        echo "  これは、DOMツリー上で 'これは' が '太字' の前に位置することを意味します。\n";
68    } else {
69        echo "  結果: 'これは' テキストノードは '太字' テキストノードに先行していません。\n";
70    }
71    echo "\n";
72
73    // --- 例3: その他の比較 (DOCUMENT_POSITION_FOLLOWING) ---
74    // 逆に '太字' テキストノードが 'これは' テキストノードに後続するかを確認します。
75    echo "--- '太字' テキストノードと 'これは' テキストノードの比較 ('太字' Text vs 'これは' Text) ---\n";
76    $result_b_text_p1_text = $b_text_node_child->compareDocumentPosition($p1_text_node_child);
77
78    if ($result_b_text_p1_text & Node::DOCUMENT_POSITION_FOLLOWING) {
79        echo "  結果: '太字' テキストノードは 'これは' テキストノードに後続しています。\n";
80        echo "  (返されたフラグが " . Node::DOCUMENT_POSITION_FOLLOWING . " に該当)\n";
81        echo "  これは、DOMツリー上で '太字' が 'これは' の後に位置することを意味します。\n";
82    } else {
83        echo "  結果: '太字' テキストノードは 'これは' テキストノードに後続していません。\n";
84    }
85    echo "\n";
86}
87
88// 関数を実行してデモンストレーションを開始します。
89demonstrateNodePositionComparison();
90

PHP 8のDOM拡張では、ウェブページの構造を表すDOMノード間の位置関係をプログラムで比較する機能が提供されています。その中心となるのが、Dom\Nodeクラス（そしてそれを継承するDom\CharacterDataのようなクラス）で利用できる定数と、compareDocumentPosition()メソッドです。

Dom\CharacterData::DOCUMENT_POSITION_CONTAINED_BY定数は整数値を持ち、主にcompareDocumentPosition()メソッドの戻り値と組み合わせて使用されます。compareDocumentPosition()メソッドは、二つのDOMノードの相対的な位置関係を示すビットマスク（複数の状態を組み合わせた数値）を整数として返します。この定数は、比較対象のノードが基準となるノードに「含まれている」状態を示すフラグの一つです。サンプルコードでは、'太字'というテキストノードがその親要素である<b>要素に実際に含まれていることを、この定数を用いて判定しています。

また、キーワードとして示されたdocument_position_precedingに関連するNode::DOCUMENT_POSITION_PRECEDING定数も同様に整数値を持ち、一方のノードがもう一方のノードのDOMツリー上の文書順で「先行している」（前にある）状態を示すフラグです。サンプルコードでは、'これは'というテキストノードが'太字'というテキストノードよりもDOMツリー上で前に位置するかどうかをこの定数で確認しています。逆に「後続している」場合はNode::DOCUMENT_POSITION_FOLLOWING定数で判定できます。これらの定数とメソッドを組み合わせることで、開発者は複雑なDOMツリー内でのノードの親子関係や順序を正確に把握し、プログラムで柔軟に処理できるようになります。

Copy
1<?php
2
3/**
4 * DOMノードの位置関係を比較し、あるノードが別のノードに含まれるかを確認する。
5 *
6 * この関数は Dom\Node::compareDocumentPosition メソッドと
7 * Dom\CharacterData::DOCUMENT_POSITION_CONTAINED_BY 定数を使用して、
8 * ノード間の包含関係を判定する方法を示します。
9 * PHP 8以降でDom拡張が有効な環境で動作します。
10 */
11function checkNodeContainment(): void
12{
13    // 新しいDOMドキュメントを作成します。
14    $document = new DOMDocument();
15
16    // 親ノードとなる要素 'parent' を作成し、ドキュメントに追加します。
17    $parentElement = $document->createElement('parent');
18    $document->appendChild($parentElement);
19
20    // 子ノードとなる要素 'child' を作成し、親ノードに追加します。
21    // この子ノードを親ノードに追加することで、包含関係が成立します。
22    $childElement = $document->createElement('child');
23    $parentElement->appendChild($childElement);
24
25    echo "--- DOMノードの包含関係を確認 ---\n";
26
27    // 1. $childElement が $parentElement に含まれるか比較します。
28    // compareDocumentPosition メソッドは、呼び出し元のノード($childElement)が
29    // 引数のノード($parentElement)に対してどのような位置関係にあるかを示す
30    // ビットマスク（整数値）を返します。
31    $position = $childElement->compareDocumentPosition($parentElement);
32
33    // Dom\CharacterData::DOCUMENT_POSITION_CONTAINED_BY 定数と
34    // ビット論理積 (&) を使って、包含関係が「子->親」方向で成立しているかを判定します。
35    // この定数は Dom\Node を継承する Dom\CharacterData に定義されています。
36    if (($position & Dom\CharacterData::DOCUMENT_POSITION_CONTAINED_BY) === Dom\CharacterData::DOCUMENT_POSITION_CONTAINED_BY) {
37        echo "結果: '{$childElement->nodeName}' は '{$parentElement->nodeName}' に含まれています。\n";
38    } else {
39        echo "結果: '{$childElement->nodeName}' は '{$parentElement->nodeName}' に含まれていません。\n";
40    }
41    echo "\n";
42
43    // 2. 逆のケースも確認します。
44    // $parentElement が $childElement に含まれるか比較します。
45    // この場合、親ノードが子ノードを「含む」関係にあるため、
46    // DOCUMENT_POSITION_CONTAINED_BY は当てはまりません。
47    $positionInverse = $parentElement->compareDocumentPosition($childElement);
48
49    if (($positionInverse & Dom\CharacterData::DOCUMENT_POSITION_CONTAINED_BY) === Dom\CharacterData::DOCUMENT_POSITION_CONTAINED_BY) {
50        echo "結果: '{$parentElement->nodeName}' は '{$childElement->nodeName}' に含まれています。(誤り)\n";
51    } else {
52        echo "結果: '{$parentElement->nodeName}' は '{$childElement->nodeName}' に含まれていません。\n";
53        // 補足: このケースでは DOCUMENT_POSITION_CONTAINS が該当します。
54        // Dom\CharacterData::DOCUMENT_POSITION_CONTAINS と比較することもできます。
55        if (($positionInverse & Dom\CharacterData::DOCUMENT_POSITION_CONTAINS) === Dom\CharacterData::DOCUMENT_POSITION_CONTAINS) {
56            echo "  (補足: しかし、'{$parentElement->nodeName}' は '{$childElement->nodeName}' を含んでいます。)\n";
57        }
58    }
59}
60
61// 関数を実行します。
62checkNodeContainment();
63

このサンプルコードは、PHPのDOM（Document Object Model）操作において、あるDOMノードが別のノードに「含まれているか」という包含関係を判定する方法を示しています。主要な要素として、Dom\Node::compareDocumentPositionメソッドと、定数Dom\CharacterData::DOCUMENT_POSITION_CONTAINED_BYが用いられます。

compareDocumentPositionメソッドは、呼び出し元のノードと引数で指定されたノードとの位置関係を、複数の状態を表現できる整数値（ビットマスク）として返します。このメソッドは比較対象のノードを引数として一つ取り、ノード間の関係を示す整数値を戻り値とします。

ここで使用されるDom\CharacterData::DOCUMENT_POSITION_CONTAINED_BY定数は、呼び出し元のノードが引数のノードに「含まれている」場合に、compareDocumentPositionメソッドの結果に含まれるべき特定の整数値を表します。この定数自体は引数を取らず、整数値を返します。

コードではまず、親要素と子要素を作成し、子要素が親要素に実際に含まれているケースを比較します。compareDocumentPositionの結果とこの定数をビット論理積（&）で比較することで、包含関係が正確に検出されます。次に、親要素が子要素に含まれているかという逆のケースを検証します。この場合、親ノードは子ノードを含んでいますが、子ノードに「含まれている」わけではないため、DOCUMENT_POSITION_CONTAINED_BY定数を用いた判定では「含まれていません」という結果になります。このように、この定数はDOMツリーにおける厳密な包含関係を識別する際に役立ちます。