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

Copy
1<?php
2
3/**
4 * PHPのDOM拡張におけるノード位置比較のデモンストレーションを行います。
5 * Dom\Text::DOCUMENT_POSITION_CONTAINS 定数の使い方を、
6 * Dom\Node::compareDocumentPosition() メソッドとの関連で示します。
7 *
8 * この関数は単体で動作し、システムエンジニアを目指す初心者が
9 * ドキュメントオブジェクトモデル (DOM) のノード間の関係性を理解するのに役立ちます。
10 */
11function demonstrateDocumentPositionContains(): void
12{
13    // 1. DOMDocument オブジェクトを作成します。
14    // HTML5 ドキュメントとして扱い、整形されたXMLを出力するように設定します。
15    $dom = new DOMDocument('1.0', 'UTF-8');
16    $dom->formatOutput = true; // 出力を見やすく整形します
17
18    // 2. いくつかの要素ノードとテキストノードを作成し、DOMツリーに階層的に追加します。
19    // root要素 -> parent要素 -> child要素 -> textNode の順にネストします。
20    $root = $dom->createElement('root');
21    $dom->appendChild($root); // ドキュメントのルートに'root'要素を追加
22
23    $parent = $dom->createElement('parent');
24    $root->appendChild($parent); // 'root'の下に'parent'要素を追加
25
26    $child = $dom->createElement('child');
27    $parent->appendChild($child); // 'parent'の下に'child'要素を追加
28
29    $textNode = $dom->createTextNode('Hello World');
30    $child->appendChild($textNode); // 'child'の下にテキストノードを追加
31
32    echo "--- 構築されたDOMツリー ---\n";
33    echo $dom->saveXML() . "\n"; // 構築されたDOMツリーをXML形式で表示します
34
35    // 3. Dom\Node::compareDocumentPosition() メソッドを使って、2つのノード間の位置関係を比較します。
36    // このメソッドは、比較元のノードと比較対象のノードの相対的な位置を示すビットマスクを返します。
37
38    echo "--- ノード位置の比較例 ---\n";
39
40    // 例1: 'parent' ノードが 'child' ノードを「含む」かどうかの比較
41    // ここでは 'parent' が 'child' を含んでいるため、結果には Dom\Text::DOCUMENT_POSITION_CONTAINS が含まれます。
42    $positionResult1 = $parent->compareDocumentPosition($child);
43
44    echo "[比較 1]: 'parent' ノード と 'child' ノード\n";
45    echo "  - 比較元ノード: 'parent' 要素\n";
46    echo "  - 比較対象ノード: 'child' 要素\n";
47    echo "  - compareDocumentPosition() の結果 (ビットマスク): " . $positionResult1 . "\n";
48
49    // 4. 比較結果を Dom\Text::DOCUMENT_POSITION_CONTAINS 定数とビットAND演算子 (&) で比較し、関係性を判断します。
50    // ビットAND演算子は、両方の値に共通して設定されているビットがある場合に真と判断します。
51    if ($positionResult1 & Dom\Text::DOCUMENT_POSITION_CONTAINS) {
52        echo "  - 結果: 'parent' ノードは 'child' ノードを **含んでいます**。\n";
53    } else {
54        echo "  - 結果: 'parent' ノードは 'child' ノードを **含んでいません**。\n";
55    }
56    echo "\n";
57
58    // 例2: 'child' ノードが 'parent' ノードを「含む」かどうかの比較
59    // 'child' は 'parent' に含まれているため、この場合 Dom\Text::DOCUMENT_POSITION_CONTAINS は含まれません。
60    // 代わりに Dom\Text::DOCUMENT_POSITION_CONTAINED_BY (比較元が比較対象に含まれている) が含まれます。
61    $positionResult2 = $child->compareDocumentPosition($parent);
62
63    echo "[比較 2]: 'child' ノード と 'parent' ノード\n";
64    echo "  - 比較元ノード: 'child' 要素\n";
65    echo "  - 比較対象ノード: 'parent' 要素\n";
66    echo "  - compareDocumentPosition() の結果 (ビットマスク): " . $positionResult2 . "\n";
67
68    if ($positionResult2 & Dom\Text::DOCUMENT_POSITION_CONTAINS) {
69        echo "  - 結果: 'child' ノードは 'parent' ノードを **含んでいます**。\n";
70    } else {
71        echo "  - 結果: 'child' ノードは 'parent' ノードを **含んでいません**。\n";
72    }
73    echo "\n";
74
75    // 例3: 'root' ノードが作成したテキストノードを「含む」かどうかの比較
76    // 'root' は 'child' を介してテキストノードを含んでいるため、結果には Dom\Text::DOCUMENT_POSITION_CONTAINS が含まれます。
77    $positionResult3 = $root->compareDocumentPosition($textNode);
78
79    echo "[比較 3]: 'root' ノード と テキストノード\n";
80    echo "  - 比較元ノード: 'root' 要素\n";
81    echo "  - 比較対象ノード: テキストノード 'Hello World'\n";
82    echo "  - compareDocumentPosition() の結果 (ビットマスク): " . $positionResult3 . "\n";
83
84    if ($positionResult3 & Dom\Text::DOCUMENT_POSITION_CONTAINS) {
85        echo "  - 結果: 'root' ノードはテキストノードを **含んでいます**。\n";
86    } else {
87        echo "  - 結果: 'root' ノードはテキストノードを **含んでいません**。\n";
88    }
89    echo "\n";
90}
91
92// 関数を実行し、DOMノード間の位置関係のデモンストレーションを開始します。
93demonstrateDocumentPositionContains();

PHPのDOM拡張機能は、HTMLやXMLドキュメントの構造をプログラムから操作するためのものです。Dom\Text::DOCUMENT_POSITION_CONTAINS定数は、DOMツリー内のノード間で、あるノードが別のノードを「含んでいる」という位置関係を示すために使用されます。この定数自体に引数や戻り値はありませんが、Dom\Node::compareDocumentPosition()メソッドの戻り値を解釈する際に利用されます。

Dom\Node::compareDocumentPosition()メソッドは、比較元のノードと比較対象のノードの相対的な位置関係を表す整数値（ビットマスク）を返します。サンプルコードでは、まずDOMDocumentオブジェクトを作成し、要素ノードやテキストノードを階層的に追加してDOMツリーを構築しています。

構築されたDOMツリーに対して、例えば親ノードが子ノードを、あるいは祖先ノードが子孫ノードをそれぞれ含んでいるかを確認します。そのために、compareDocumentPosition()メソッドの戻り値とDom\Text::DOCUMENT_POSITION_CONTAINS定数をビットAND演算子 (&) で比較します。この演算で結果が真であれば、比較元のノードが比較対象のノードを実際に含んでいることを意味します。この仕組みにより、システムエンジニアの初心者は、DOMツリーにおけるノードの階層的な関係性をプログラムで効率的に判断する方法を学ぶことができます。

Copy
1<?php
2
3/**
4 * Dom\Node::DOCUMENT_POSITION_CONTAINS 定数を使用して、DOMノード間の親子関係を判断する例。
5 *
6 * この関数は、HTML文字列からDOMツリーを構築し、2つのノード間の位置関係を比較します。
7 * 特に、`compareDocumentPosition()` メソッドの戻り値と
8 * `Dom\Node::DOCUMENT_POSITION_CONTAINS` 定数（PHP 8 Dom拡張）を組み合わせて、
9 * 一方のノードがもう一方のノードの祖先である（つまり含んでいる）かどうかを判定します。
10 * システムエンジニアを目指す初心者の方にも、具体的なDOM操作と定数の利用方法を理解しやすいよう、
11 * 必要最低限のコメントを加えています。
12 *
13 * PHPのDom拡張において、DOCUMENT_POSITION_CONTAINS定数はDom\Nodeクラスに定義されています。
14 * Dom\TextクラスはDom\Nodeを継承しているため、Dom\Textのインスタンスを比較対象として
15 * この定数を使用することが可能です。
16 */
17function demonstrateDomNodeContainment(): void
18{
19    // HTML文字列からDOMドキュメントを構築します。
20    // PHP 8ではDom\Documentクラスを使用します。
21    $document = new Dom\Document();
22    $document->loadHTML('<html><body><div id="parent"><p id="child_p">これは<span id="grandchild_span">テキスト</span>です。</p></div></body></html>');
23
24    // 比較に使用するノードを取得します。
25    /** @var Dom\Element $parentNode 'parent' IDを持つdiv要素 */
26    $parentNode = $document->getElementById('parent');
27    /** @var Dom\Element $childPNode 'child_p' IDを持つp要素 */
28    $childPNode = $document->getElementById('child_p');
29    /** @var Dom\Element $grandchildSpanNode 'grandchild_span' IDを持つspan要素 */
30    $grandchildSpanNode = $document->getElementById('grandchild_span');
31    /** @var Dom\Text $textNode span要素内のテキストノード "テキスト"
32     * Dom\TextはDom\Nodeを継承しており、compareDocumentPositionを利用できます。
33     */
34    $textNode = $grandchildSpanNode->firstChild;
35
36
37    echo "--- ノードの包含関係の確認 ---" . PHP_EOL;
38
39    // 例1: 親ノードが子ノードを含んでいるか
40    // $parentNode は $childPNode の親なので、包含関係があります。
41    $position1 = $parentNode->compareDocumentPosition($childPNode);
42    echo "1. 'parent' (div) と 'child_p' (p) の比較:" . PHP_EOL;
43    if (($position1 & Dom\Node::DOCUMENT_POSITION_CONTAINS) === Dom\Node::DOCUMENT_POSITION_CONTAINS) {
44        echo "   - 'parent' は 'child_p' を含んでいます。" . PHP_EOL;
45    } else {
46        echo "   - 'parent' は 'child_p' を含んでいません。" . PHP_EOL;
47    }
48    echo "   (比較結果のビットマスク: " . $position1 . ")" . PHP_EOL . PHP_EOL;
49
50    // 例2: 子ノードが親ノードを含んでいるか (逆のパターン)
51    // $childPNode は $parentNode の子なので、包含関係はありません。
52    $position2 = $childPNode->compareDocumentPosition($parentNode);
53    echo "2. 'child_p' (p) と 'parent' (div) の比較:" . PHP_EOL;
54    if (($position2 & Dom\Node::DOCUMENT_POSITION_CONTAINS) === Dom\Node::DOCUMENT_POSITION_CONTAINS) {
55        echo "   - 'child_p' は 'parent' を含んでいます。" . PHP_EOL;
56    } else {
57        echo "   - 'child_p' は 'parent' を含んでいません。" . PHP_EOL;
58    }
59    echo "   (比較結果のビットマスク: " . $position2 . ")" . PHP_EOL . PHP_EOL;
60
61    // 例3: 祖先ノードが子孫テキストノードを含んでいるか
62    // Dom\Text ノードも比較対象にできます。
63    // $parentNode は $textNode の祖先なので、包含関係があります。
64    $position3 = $parentNode->compareDocumentPosition($textNode);
65    echo "3. 'parent' (div) とテキストノード ('テキスト') の比較:" . PHP_EOL;
66    if (($position3 & Dom\Node::DOCUMENT_POSITION_CONTAINS) === Dom\Node::DOCUMENT_POSITION_CONTAINS) {
67        echo "   - 'parent' はテキストノードを含んでいます。" . PHP_EOL;
68    } else {
69        echo "   - 'parent' はテキストノードを含んでいません。" . PHP_EOL;
70    }
71    echo "   (比較結果のビットマスク: " . $position3 . ")" . PHP_EOL . PHP_EOL;
72
73    // 例4: 同一ノード間の比較
74    // DOM仕様では、ノードはそれ自身を含んでいるとは見なされません。
75    $position4 = $parentNode->compareDocumentPosition($parentNode);
76    echo "4. 'parent' (div) と自身 ('parent' div) の比較:" . PHP_EOL;
77    if (($position4 & Dom\Node::DOCUMENT_POSITION_CONTAINS) === Dom\Node::DOCUMENT_POSITION_CONTAINS) {
78        echo "   - 'parent' は自身を含んでいます。(DOM仕様上、ノードは自身を含んでいるとは見なされません)" . PHP_EOL;
79    } else {
80        echo "   - 'parent' は自身を含んでいません。(DOM仕様上、ノードは自身を含んでいるとは見なされません)" . PHP_EOL;
81    }
82    echo "   (比較結果のビットマスク: " . $position4 . ")" . PHP_EOL . PHP_EOL;
83}
84
85// 関数を実行して、DOMノードの包含関係を確認します。
86demonstrateDomNodeContainment();
87

PHP 8のDom拡張で提供されるDom\Node::DOCUMENT_POSITION_CONTAINSは、DOM（Document Object Model）ノード間の包含関係を判断するために用いられる定数です。この定数自体は引数を取らず、戻り値も持ちませんが、特定のビットパターンを持つ数値として定義されています。主にDom\Node::compareDocumentPosition()メソッドの戻り値と組み合わせて使用されます。

compareDocumentPosition()メソッドは、比較対象の2つのノード間の相対的な位置関係を示すビットマスクを返します。この戻り値とDom\Node::DOCUMENT_POSITION_CONTAINS定数をビット論理積（&）で比較することで、一方のノードがもう一方のノードを「含んでいる」（つまり、祖先ノードである）かどうかを正確に判定できます。

サンプルコードでは、まずHTML文字列からDOMドキュメントを構築し、親要素、子要素、さらにはその内部にあるテキストノードといった複数のノードを取得しています。そして、これらのノード間でcompareDocumentPosition()を実行し、その結果がDOCUMENT_POSITION_CONTAINS定数を含んでいるかを判断することで、「親ノードが子ノードを含んでいるか」「祖先ノードがテキストノードを含んでいるか」といった具体的な包含関係を確認しています。Dom\TextクラスはDom\Nodeを継承しているため、テキストノードに対してもこの定数を用いた比較が可能です。これにより、システムエンジニアを目指す方も、DOMツリー内でのノードの親子関係をプログラムで明確に判定する方法を理解できます。