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

Copy
1<?php
2
3/**
4 * DOMNode::compareDocumentPosition() メソッドとDOMの定数を使ったノード間の位置関係の比較方法を示すサンプルコードです。
5 *
6 * システムエンジニアを目指す初心者の方へ:
7 * DOM (Document Object Model) は、HTMLやXML文書の構造をプログラムから操作するためのAPIです。
8 * PHPのDOM拡張機能を使うと、WebページやXML設定ファイルを読み込んで内容を解析したり、
9 * 新しい要素を追加・変更・削除したりすることができます。
10 * このサンプルでは、XML文書内の2つのノードが「文書内でどこに位置するか」を比較する方法を学びます。
11 *
12 * - DOMNode::compareDocumentPosition() は、比較対象のノードと現在のノードの関係を整数値（ビットマスク）で返します。
13 *   この返り値は、複数のDOM定数を組み合わせたものです。
14 *
15 * - DOCUMENT_POSITION_PRECEDING (値: 4): 比較対象のノードが、このメソッドを呼び出したノードよりも文書の順序で「前」に位置することを示します。
16 *   例えば、ノードBがノードAの後にあり、ノードBからノードAを比較した場合にこのフラグが立ちます。
17 *
18 * - DOCUMENT_POSITION_CONTAINED_BY (値: 16): このメソッドを呼び出したノードが、比較対象のノードに「含まれている」（子孫である）ことを示します。
19 *   例えば、テキストノードがその親要素に対して比較された場合などです。
20 *
21 * 返される値がビットマスクであるため、`&` (ビットAND演算子) を使って特定の定数が結果に含まれているかを確認します。
22 */
23function demonstrateDomNodePositionComparison(): void
24{
25    // 1. 新しいDOMDocumentを作成し、XML文書の基本構造を定義
26    $dom = new DOMDocument('1.0', 'UTF-8');
27    $dom->formatOutput = true; // 出力されるXMLを見やすくするための設定
28
29    // ルート要素を作成し、DOMにA.追加
30    $root = $dom->createElement('root');
31    $dom->appendChild($root);
32
33    // 要素Aと、その子テキストノードAを作成
34    $elementA = $dom->createElement('elementA');
35    $textNodeA = $dom->createTextNode('Hello A'); // 比較対象となるDOMTextノード
36    $elementA->appendChild($textNodeA);
37    $root->appendChild($elementA);
38
39    // 要素Bと、その子テキストノードBを作成
40    $elementB = $dom->createElement('elementB');
41    $textNodeB = $dom->createTextNode('World B'); // 比較対象となるDOMTextノード
42    $elementB->appendChild($textNodeB);
43    $root->appendChild($elementB);
44
45    // 要素C (要素Bの子) と、その子テキストノードCを作成
46    $elementC = $dom->createElement('elementC');
47    $textNodeC = $dom->createTextNode('PHP C'); // 比較対象となるDOMTextノード
48    $elementC->appendChild($textNodeC);
49    $elementB->appendChild($elementC); // elementCはelementBの子孫
50
51    echo "--- 生成されたXML構造 ---\n";
52    echo $dom->saveXML();
53    echo "\n";
54
55    echo "--- ノードの位置関係の比較結果 ---\n";
56
57    // 事例1: DOCUMENT_POSITION_PRECEDING のデモンストレーション
58    // textNodeB は文書の順序で textNodeA の「後」に位置します。
59    // したがって、textNodeB から textNodeA を比較すると、textNodeA は textNodeB の「前」に位置するという結果になります。
60    $resultBvsA = $textNodeB->compareDocumentPosition($textNodeA);
61    echo "1. 'World B' ノードから 'Hello A' ノードを比較:\n";
62    echo "   - 比較結果の数値コード: " . $resultBvsA . " (DOCUMENT_POSITION_PRECEDINGは4)\n";
63    if ($resultBvsA & DOCUMENT_POSITION_PRECEDING) {
64        echo "   -> ✅ 'Hello A' は 'World B' よりも文書の順序で「前」に位置します。\n";
65    } else {
66        echo "   -> ❌ 'Hello A' は 'World B' よりも文書の順序で「前」には位置しません。\n";
67    }
68    // 補足: 逆の比較で DOCUMENT_POSITION_FOLLOWING も確認できます。
69    $resultAvsB = $textNodeA->compareDocumentPosition($textNodeB);
70    echo "   - 'Hello A' ノードから 'World B' ノードを比較: " . $resultAvsB . " (DOCUMENT_POSITION_FOLLOWINGは8)\n";
71    if ($resultAvsB & DOCUMENT_POSITION_FOLLOWING) {
72        echo "   -> 'World B' は 'Hello A' よりも文書の順序で「後」に位置します。\n";
73    }
74
75    echo "\n";
76
77    // 事例2: DOCUMENT_POSITION_CONTAINED_BY のデモンストレーション
78    // textNodeC は elementB の子孫ノードです。
79    // したがって、textNodeC から elementB を比較すると、textNodeC は elementB に「含まれている」という結果になります。
80    $resultCvsB = $textNodeC->compareDocumentPosition($elementB);
81    echo "2. 'PHP C' ノードから 'elementB' ノードを比較:\n";
82    echo "   - 比較結果の数値コード: " . $resultCvsB . " (DOCUMENT_POSITION_CONTAINED_BYは16)\n";
83    if ($resultCvsB & DOCUMENT_POSITION_CONTAINED_BY) {
84        echo "   -> ✅ 'PHP C' は 'elementB' に「含まれています」（子孫です）。\n";
85    } else {
86        echo "   -> ❌ 'PHP C' は 'elementB' に「含まれていません」。\n";
87    }
88    // 補足: 逆の比較で DOCUMENT_POSITION_CONTAINS も確認できます。
89    $resultBvsC = $elementB->compareDocumentPosition($textNodeC);
90    echo "   - 'elementB' ノードから 'PHP C' ノードを比較: " . $resultBvsC . " (DOCUMENT_POSITION_CONTAINSは80 = 64(CONTAINS) + 16(CONTAINED_BY for CvsB but it should be CONTAINS for BvsC) => 20 (CONTAINS + FOLLOWING))\n";
91    if ($resultBvsC & DOCUMENT_POSITION_CONTAINS) { // DOCUMENT_POSITION_CONTAINS (値: 8) と DOCUMENT_POSITION_FOLLOWING (値: 4) を組み合わせた値の場合があります。
92        echo "   -> 'elementB' は 'PHP C' を「含んでいます」（親/祖先です）。\n";
93    }
94}
95
96// 関数を実行してサンプルコードの動作を確認
97demonstrateDomNodePositionComparison();
98

PHPのDOM拡張機能は、HTMLやXML文書の構造をプログラムで操作するための機能を提供します。この機能を使うと、Webページや設定ファイルを読み込み、要素を追加したり変更したりできます。DOMNode::compareDocumentPosition()メソッドは、2つのDOMノードが文書内でどのような位置関係にあるかを比較し、その結果を数値（ビットマスク）で返します。この戻り値は、複数のDOM定数を組み合わせたものです。

DOCUMENT_POSITION_CONTAINED_BYは、このメソッドを呼び出したノードが、比較対象のノードに「含まれている」（つまり子孫ノードである）場合に結果に含まれる定数です。例えば、テキストノードがその親要素に対して比較される際に使用されます。一方、DOCUMENT_POSITION_PRECEDINGは、比較対象のノードが、現在のノードよりも文書の順序で「前」に位置する場合に結果に含まれます。これらの定数の値は整数であり、結果の数値とビットAND演算子（&）を使って、特定の関係が成立するかどうかを判断します。

このサンプルコードでは、XML文書を作成し、DOMNode::compareDocumentPosition()メソッドを使って異なるノード間の位置関係を具体的に比較しています。例えば、「PHP C」というテキストノードが「elementB」という要素に「含まれているか」や、「Hello A」というテキストノードが「World B」というテキストノードよりも文書の順序で「前にあるか」を、これらの定数を用いて確認する方法が示されています。これにより、文書内の複雑なノード構造をプログラムで効率的に解析できるようになります。

Copy
1<?php
2
3/**
4 * DOMノードの位置関係を比較するDOMNode::compareDocumentPosition()メソッドと、
5 * DOMNode::DOCUMENT_POSITION_CONTAINED_BY 定数、および
6 * DOMNode::DOCUMENT_POSITION_CONTAINS 定数の使用例を示します。
7 *
8 * この関数は、システムエンジニアを目指す初心者の方にも理解しやすいように、
9 * HTMLドキュメント内の特定のテキストノードがその親要素に「含まれている」か、
10 * あるいは親要素がテキストノードを「含んでいる」かを判定するデモンストレーションを行います。
11 *
12 * PHPのDOM拡張において、DOCUMENT_POSITION_CONTAINED_BY などの定数はDOMNodeクラスに定義されています。
13 * DOMTextクラスはDOMNodeクラスを継承しているため、DOMTextのインスタンス（テキストノード）を
14 * 他のノードと比較する際にもこれらの定数を利用して位置関係を正確に判断できます。
15 */
16function demonstrateDomNodePositionComparison(): void
17{
18    // 1. DOMDocument オブジェクトを作成し、HTMLコンテンツを読み込む
19    $dom = new DOMDocument();
20    // HTMLパース時の自動的な<html><body>要素の付加を抑制し、シンプルなDOM構造を維持します。
21    $htmlContent = '<div><p>これは<em>サンプル</em>のテキストです。</p></div>';
22    $dom->loadHTML($htmlContent, LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD);
23
24    // 2. 比較対象となるDOMノードを取得
25
26    // まず、親要素となる <div> タグを取得します。
27    $parentElement = $dom->getElementsByTagName('div')->item(0);
28    if (!$parentElement instanceof DOMElement) {
29        echo "エラー: 親要素 (div) が見つかりませんでした。HTML構造を確認してください。\n";
30        return;
31    }
32
33    // 次に、比較のメインとなるテキストノードを取得します。
34    // ここでは "サンプル" という文字列を持つテキストノードを探します。
35    // <p> -> <em> の子要素であるテキストノードを取得します。
36    $emElement = $dom->getElementsByTagName('em')->item(0);
37    $textNode = $emElement ? $emElement->firstChild : null;
38
39    if (!$textNode instanceof DOMText) {
40        echo "エラー: テキストノード 'サンプル' が見つかりませんでした。HTML構造を確認してください。\n";
41        return;
42    }
43
44    echo "--- DOMノードの位置関係の比較 --- \n";
45    echo "ノードA (親要素): <" . $parentElement->nodeName . ">\n";
46    echo "ノードB (テキストノード): '" . $textNode->nodeValue . "'\n\n";
47
48    // --- ケース 1: テキストノード (B) が親要素 (A) に「含まれている」かを確認 ---
49    // DOMNode::compareDocumentPosition() メソッドは、呼び出し元ノードから
50    // 比較対象のノードへの相対的な位置関係をビットマスクで返します。
51    // ここでは $textNode (ノードB) が $parentElement (ノードA) と比較されます。
52    // 期待される結果: $textNode は $parentElement に含まれているので、
53    // DOMNode::DOCUMENT_POSITION_CONTAINED_BY フラグがセットされます。
54    $positionFromTextNode = $textNode->compareDocumentPosition($parentElement);
55
56    echo "■ ノードB ('" . $textNode->nodeValue . "') からノードA ('" . $parentElement->nodeName . "') を比較:\n";
57    echo "  戻り値 (ビットマスク): " . $positionFromTextNode . "\n";
58
59    // ビット論理AND演算子 (&) を使用して、特定のフラグがセットされているかを確認します。
60    if ($positionFromTextNode & DOMNode::DOCUMENT_POSITION_CONTAINED_BY) {
61        echo "  - 結果: 正しく、ノードB はノードA に含まれています (DOCUMENT_POSITION_CONTAINED_BY)。\n";
62    } else {
63        echo "  - 結果: 誤り、ノードB はノードA に含まれていません (DOCUMENT_POSITION_CONTAINED_BY フラグがありません)。\n";
64    }
65    // ノードBがノードAを含んでいるか（これはこのケースでは通常発生しません）
66    if ($positionFromTextNode & DOMNode::DOCUMENT_POSITION_CONTAINS) {
67        echo "  - 補足: ノードB はノードA を含んでいます (DOCUMENT_POSITION_CONTAINS)。[これは通常起こりません]\n";
68    }
69    echo "\n";
70
71    // --- ケース 2: 親要素 (A) がテキストノード (B) を「含んでいる」かを確認 ---
72    // 今度は $parentElement (ノードA) から $textNode (ノードB) を比較します。
73    // 期待される結果: $parentElement は $textNode を含んでいるので、
74    // DOMNode::DOCUMENT_POSITION_CONTAINS フラグがセットされます。
75    $positionFromParentElement = $parentElement->compareDocumentPosition($textNode);
76
77    echo "■ ノードA ('" . $parentElement->nodeName . "') からノードB ('" . $textNode->nodeValue . "') を比較:\n";
78    echo "  戻り値 (ビットマスク): " . $positionFromParentElement . "\n";
79
80    if ($positionFromParentElement & DOMNode::DOCUMENT_POSITION_CONTAINS) {
81        echo "  - 結果: 正しく、ノードA はノードB を含んでいます (DOCUMENT_POSITION_CONTAINS)。\n";
82    } else {
83        echo "  - 結果: 誤り、ノードA はノードB を含んでいません (DOCUMENT_POSITION_CONTAINS フラグがありません)。\n";
84    }
85    // ノードAがノードBに含まれているか（これもこのケースでは通常発生しません）
86    if ($positionFromParentElement & DOMNode::DOCUMENT_POSITION_CONTAINED_BY) {
87        echo "  - 補足: ノードA はノードB に含まれています (DOCUMENT_POSITION_CONTAINED_BY)。[これは通常起こりません]\n";
88    }
89    echo "\n";
90}
91
92// 関数を実行して、DOMノードの位置関係の比較デモンストレーションを開始します。
93demonstrateDomNodePositionComparison();
94

このコードは、PHPのDOM拡張機能を使って、HTMLドキュメント内のDOMノード間の位置関係を比較する方法を示しています。具体的には、DOMNode::compareDocumentPosition()メソッドを利用して、あるノードが別のノードに「含まれている」か、または「含んでいる」かを判定します。

compareDocumentPosition()メソッドは、比較結果をビットマスク形式の整数値で返します。この戻り値は、DOMNode::DOCUMENT_POSITION_CONTAINED_BYやDOMNode::DOCUMENT_POSITION_CONTAINSといった定数とビット論理AND演算子&で比較することで、特定の関係性が存在するかどうかを判別できます。

DOMNode::DOCUMENT_POSITION_CONTAINED_BY定数は、メソッドを呼び出したノードが比較対象のノードに「含まれている」場合にセットされるフラグを示します。一方、DOMNode::DOCUMENT_POSITION_CONTAINS定数は、呼び出したノードが比較対象のノードを「含んでいる」場合にセットされるフラグです。これらの定数はDOMNodeクラスに定義されており、それを継承するDOMTextクラスのインスタンス（テキストノード）でも利用可能です。

サンプルコードでは、<div>要素と、その中に含まれるテキストノード「サンプル」を例に、これらの定数がどのように使われ、ノードの位置関係が判定されるかを分かりやすく解説しています。