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

Copy
1<?php
2
3// PHP 8 の新しい DOM 拡張を使用します。
4// Dom\Document は DOM ツリー全体を管理するクラスです。
5// Dom\Element は HTML/XML の要素（例: <div>, <p>）を表すクラスです。
6// Dom\CDATASection は CDATA セクションを表すクラスです。
7// Dom\Node は全ての DOM ノードの基底クラスであり、比較定数を含みます。
8use Dom\Document;
9use Dom\CDATASection;
10use Dom\Element;
11use Dom\Node;
12
13/**
14 * DOM ツリー内のノード位置関係を比較するサンプルコード。
15 *
16 * この関数は、Dom\Node::compareDocumentPosition() メソッドを使用し、
17 * ドキュメントオブジェクトモデル (DOM) ツリー内のあるノードが別のノードに対し
18 * どのような位置関係にあるかを判定する方法を示します。
19 *
20 * 特に、指定された定数 DOCUMENT_POSITION_CONTAINED_BY と、
21 * キーワードに関連する DOCUMENT_POSITION_PRECEDING の使い方に焦点を当てます。
22 *
23 * DOCUMENT_POSITION_CONTAINED_BY: 比較対象のノードが、このノードの内部に含まれている場合に設定されます。
24 * DOCUMENT_POSITION_PRECEDING: 比較対象のノードが、このノードよりも DOM ツリー内で物理的に「前」にある場合に設定されます。
25 */
26function demonstrateDomNodePositionComparison(): void
27{
28    // 1. 新しい DOM ドキュメントを作成します。
29    $document = new Document();
30
31    // 2. ルートとなる div 要素を作成し、ドキュメントに追加します。
32    $rootElement = $document->createElement('div');
33    $document->appendChild($rootElement);
34
35    // 3. ルート要素の子として p 要素を作成し、追加します。
36    $paragraphElement = $document->createElement('p');
37    $rootElement->appendChild($paragraphElement);
38    $paragraphElement->textContent = 'これは最初のパラグラフです。';
39
40    // 4. p 要素の子として CDATASection を作成し、追加します。
41    // CDATASection は、XML/HTML で特殊文字をエスケープせずに含めるためのセクションです。
42    $cdataSection = $document->createCDATASection('<![CDATA[このテキストは <マークアップ> も含みます]]>');
43    $paragraphElement->appendChild($cdataSection);
44
45    // 5. ルート要素の別の兄弟として span 要素を作成し、追加します。
46    // この span 要素は p 要素の後に位置します。
47    $spanElement = $document->createElement('span');
48    $rootElement->appendChild($spanElement);
49    $spanElement->textContent = 'これは後続のスパンです。';
50
51    echo "--- DOM ノードの位置関係比較 ---" . PHP_EOL . PHP_EOL;
52
53    // --- 比較例 1: 子要素と親要素の関係 ---
54    // paragraphElement (子) が rootElement (親) に含まれているかをチェックします。
55    $positionResult1 = $paragraphElement->compareDocumentPosition($rootElement);
56    echo "1. パラグラフ要素 vs ルート要素:" . PHP_EOL;
57    if ($positionResult1 & Node::DOCUMENT_POSITION_CONTAINED_BY) {
58        echo "   - パラグラフ要素はルート要素に「含まれています (CONTAINED_BY)」。" . PHP_EOL;
59    } else {
60        echo "   - パラグラフ要素はルート要素に「含まれていません」。" . PHP_EOL;
61    }
62    echo PHP_EOL;
63
64    // --- 比較例 2: 親要素と子要素の関係 ---
65    // rootElement (親) が paragraphElement (子) を含んでいるかをチェックします。
66    $positionResult2 = $rootElement->compareDocumentPosition($paragraphElement);
67    echo "2. ルート要素 vs パラグラフ要素:" . PHP_EOL;
68    if ($positionResult2 & Node::DOCUMENT_POSITION_CONTAINS) {
69        echo "   - ルート要素はパラグラフ要素を「含んでいます (CONTAINS)」。" . PHP_EOL;
70    } else {
71        echo "   - ルート要素はパラグラフ要素を「含んでいません」。" . PHP_EOL;
72    }
73    echo PHP_EOL;
74
75    // --- 比較例 3: 兄弟要素間の関係 (PRECEDING の使用) ---
76    // paragraphElement (先行) が spanElement (後続) の「前にある (PRECEDING)」かをチェックします。
77    $positionResult3 = $paragraphElement->compareDocumentPosition($spanElement);
78    echo "3. パラグラフ要素 vs スパン要素:" . PHP_EOL;
79    if ($positionResult3 & Node::DOCUMENT_POSITION_PRECEDING) {
80        echo "   - パラグラフ要素はスパン要素の「前にあります (PRECEDING)」。" . PHP_EOL;
81    } else {
82        echo "   - パラグラフ要素はスパン要素の「前にありません」。" . PHP_EOL;
83    }
84    echo PHP_EOL;
85
86    // --- 比較例 4: 兄弟要素間の関係 (FOLLOWING の使用) ---
87    // spanElement (後続) が paragraphElement (先行) の「後にある (FOLLOWING)」かをチェックします。
88    $positionResult4 = $spanElement->compareDocumentPosition($paragraphElement);
89    echo "4. スパン要素 vs パラグラフ要素:" . PHP_EOL;
90    if ($positionResult4 & Node::DOCUMENT_POSITION_FOLLOWING) {
91        echo "   - スパン要素はパラグラフ要素の「後にあります (FOLLOWING)」。" . PHP_EOL;
92    } else {
93        echo "   - スパン要素はパラグラフ要素の「後にありません」。" . PHP_EOL;
94    }
95    echo PHP_EOL;
96
97    // --- 比較例 5: CDATASection と親要素の関係 ---
98    // cdataSection が paragraphElement に含まれているかをチェックします。
99    $positionResult5 = $cdataSection->compareDocumentPosition($paragraphElement);
100    echo "5. CDATASection vs パラグラフ要素:" . PHP_EOL;
101    if ($positionResult5 & Node::DOCUMENT_POSITION_CONTAINED_BY) {
102        echo "   - CDATASection はパラグラフ要素に「含まれています (CONTAINED_BY)」。" . PHP_EOL;
103    } else {
104        echo "   - CDATASection はパラグラフ要素に「含まれていません」。" . PHP_EOL;
105    }
106    echo PHP_EOL;
107}
108
109// 上記の関数を実行し、DOM ノードの位置関係の比較結果を表示します。
110demonstrateDomNodePositionComparison();

このサンプルコードは、PHP 8の新DOM拡張を用いて、HTMLやXMLのようなドキュメント構造（DOMツリー）におけるノードの位置関係を比較する方法を示しています。具体的には、Dom\NodeクラスのcompareDocumentPosition()メソッドを中心に、あるノードが互いに対してどの位置にあるかを判定します。

compareDocumentPosition()メソッドは、引数として比較対象のノードを受け取り、呼び出し元のノードから見た相対的な位置関係を示す整数値（ビットマスク）を返します。この戻り値は、Dom\Nodeクラスに定義された様々な定数とビット論理積（&）で比較することで、詳細な位置関係を判別できます。

例えば、Node::DOCUMENT_POSITION_CONTAINED_BY定数は、比較対象のノードが現在のノードの内部に含まれている場合に結果に含まれます。また、Node::DOCUMENT_POSITION_PRECEDING定数は、比較対象のノードが現在のノードよりもDOMツリー内で物理的に前に位置する場合に結果に含まれます。

コードでは、まず新しいDOMドキュメントといくつかの要素、そしてCDATAセクションを作成し、それらを階層的に配置しています。その後、親と子、あるいは兄弟ノードといった異なるノード間の位置関係をcompareDocumentPosition()で比較し、上記の定数やNode::DOCUMENT_POSITION_CONTAINS、Node::DOCUMENT_POSITION_FOLLOWINGといった他の定数と組み合わせて、それぞれの位置関係がどのように判定されるかを出力しています。これにより、DOMツリー内の要素が「含まれているか」「前に存在するか」などを正確に理解し、プログラムで利用できるようになります。

Copy
1<?php
2
3/**
4 * DOMノード間の位置関係、特に包含関係 (contained by) を比較するサンプルコードです。
5 *
6 * この関数は、新しいDomDocumentを作成し、親要素とその中にDom\CDATASectionノードを追加します。
7 * その後、Dom\Node::compareDocumentPosition() メソッドを使用して、
8 * Dom\CDATASectionノードが親要素に「含まれているか」どうかを判定します。
9 *
10 * 定数 DOM_DOCUMENT_POSITION_CONTAINED_BY は、参照ノードがターゲットノードに
11 * 完全に含まれている場合にセットされるビットフラグを表します。
12 * この定数は、PHPのDOM拡張でグローバルに提供されており、Dom\CDATASectionのような
13 * あらゆるDom\Nodeのサブクラスで利用できる位置関係の比較に役立ちます。
14 */
15function demonstrateDocumentPositionContains(): void
16{
17    // 1. 新しいDOMドキュメントを作成し、出力整形を有効にします。
18    $dom = new DOMDocument('1.0', 'UTF-8');
19    $dom->formatOutput = true;
20
21    // 2. 親要素「parent」を作成し、ドキュメントのルートに追加します。
22    $parentElement = $dom->createElement('parent');
23    $dom->appendChild($parentElement);
24
25    // 3. Dom\CDATASectionノードを作成し、内容を設定します。
26    // このノードはまだDOMツリーには追加されていません。
27    $cdataSection = $dom->createCDATASection('This is <CDATA> content with special characters.');
28
29    // 4. CDATASectionノードを親要素の子として追加します。
30    $parentElement->appendChild($cdataSection);
31
32    echo "--- DOMツリーの構造 ---\n";
33    echo $dom->saveXML() . "\n";
34
35    echo "--- ノード位置関係の比較 ---\n";
36
37    // 5. CDATASectionノードが親要素に含まれているかを確認します。
38    // compareDocumentPosition() メソッドは、呼び出し元のノード ($cdataSection) と引数ノード ($parentElement) の
39    // 相対的な位置関係を示すビットマスクを整数値で返します。
40    $positionResult = $cdataSection->compareDocumentPosition($parentElement);
41
42    // DOM_DOCUMENT_POSITION_CONTAINED_BY 定数は、
43    // 呼び出し元のノードが引数ノードに含まれている場合にセットされるビットフラグです。
44    // ビット論理AND演算子 (&) を使用して、この特定のフラグが結果に含まれているかを確認します。
45    if (($positionResult & DOM_DOCUMENT_POSITION_CONTAINED_BY) === DOM_DOCUMENT_POSITION_CONTAINED_BY) {
46        echo "結果: CDATASection は parentElement に含まれています。\n";
47    } else {
48        echo "結果: CDATASection は parentElement に含まれていません。\n";
49    }
50
51    echo "\n";
52
53    // 6. 逆の比較: parentElement が CDATASection に含まれているかを確認します。
54    // (通常、これはfalseになります。子ノードが親ノードを含むことはありません。)
55    $positionResultInverse = $parentElement->compareDocumentPosition($cdataSection);
56    if (($positionResultInverse & DOM_DOCUMENT_POSITION_CONTAINED_BY) === DOM_DOCUMENT_POSITION_CONTAINED_BY) {
57        echo "結果: parentElement は CDATASection に含まれています。(これは通常ありえません)\n";
58    } else {
59        echo "結果: parentElement は CDATASection に含まれていません。(これは正しい結果です)\n";
60    }
61}
62
63// 関数を実行してDOMノードの位置関係を確認します。
64demonstrateDocumentPositionContains();

このサンプルコードは、PHPのDOM拡張機能を使用して、XML/HTML文書内のノードが他のノードに「含まれているか」という位置関係を判定する方法を具体的に示しています。

PHPのDOM拡張で提供されるグローバル定数DOM_DOCUMENT_POSITION_CONTAINED_BYは、Dom\Node::compareDocumentPosition()メソッドの戻り値と組み合わせて使用されます。この定数は整数値であり、あるノードが比較対象のノードに完全に含まれている場合に、compareDocumentPosition()メソッドが返すビットマスクの特定のビットがセットされることを表します。

サンプルコードでは、まず新しいDOMDocumentを作成し、「parent」という親要素と、その中に埋め込むDom\CDATASectionノードを用意します。CDATASectionノードを親要素の子として追加することで、二つのノード間に包含関係が構築されます。

次に、$cdataSection->compareDocumentPosition($parentElement)を呼び出して、cdataSectionがparentElementに対してどのような位置関係にあるかを調べます。compareDocumentPosition()メソッドは、引数として比較対象のノードを受け取り、呼び出し元のノードとの相対的な位置関係を示すビットフラグの組み合わせを整数値で返します。この戻り値とDOM_DOCUMENT_POSITION_CONTAINED_BY定数をビット論理AND演算子 (&) で比較することで、cdataSectionがparentElementに実際に含まれているかどうかを正確に判定しています。

このように、DOM_DOCUMENT_POSITION_CONTAINED_BY定数を利用することで、DOMツリー内のノード間の親子関係や包含関係をプログラム的に効率よく確認することができます。これは、複雑なXML/HTML構造を扱うシステム開発において、特定のコンテンツが正しい位置にあるかを検証する際などに非常に有用です。