【PHP8.x】Dom\Text::DOCUMENT_POSITION_CONTAINED_BY定数の使い方
DOCUMENT_POSITION_CONTAINED_BY定数の使い方について、初心者にもわかりやすく解説します。
基本的な使い方
DOCUMENT_POSITION_CONTAINED_BY定数は、DOMノード間の位置関係を示すビットマスク値の一つを表す定数です。具体的には、あるノードが別のノードに含まれているかどうかを判断するために使用されます。DOM（Document Object Model）は、HTMLやXMLドキュメントをプログラムから操作するためのインターフェースであり、ノードはDOMにおける要素、属性、テキストなどの構成要素を指します。
この定数は、Node::compareDocumentPosition()メソッドの結果として返される値の一部として使用されます。compareDocumentPosition()メソッドは、二つのノード間の位置関係を比較し、その結果をビットマスク値として返します。返された値にDOCUMENT_POSITION_CONTAINED_BY定数が含まれている場合、一方のノードが他方のノードに含まれていることを意味します。
例えば、あるHTMLドキュメントにおいて、<body>要素内に<p>要素が存在する場合、<p>要素は<body>要素に含まれていると表現できます。このとき、<body>要素と<p>要素をcompareDocumentPosition()メソッドで比較すると、返り値にDOCUMENT_POSITION_CONTAINED_BY定数が含まれることになります。
この定数を利用することで、DOMツリー内におけるノード間の親子関係や包含関係をプログラム上で正確に判断し、適切な処理を行うことが可能になります。DOMを操作する際には、ノード間の関係性を理解することが重要であり、この定数はその理解を助けるための重要な要素となります。システムエンジニアがDOMを扱う際には、この定数の意味を理解しておくことが望ましいです。
構文(syntax)
1Dom\Text::DOCUMENT_POSITION_CONTAINED_BY
引数(parameters)
引数なし
引数はありません
戻り値(return)
int
DOCUMENT_POSITION_CONTAINED_BYは、ノードが別のノードに含まれていることを示す整数値です。
サンプルコード
PHP DOMノード位置比較を行う
1<?php 2 3/** 4 * Dom\Node の compareDocumentPosition メソッドを使用して、 5 * 2つのノード間の位置関係を比較するサンプル関数です。 6 * 7 * この関数は、主に Dom\Node::DOCUMENT_POSITION_CONTAINED_BY と 8 * Dom\Node::DOCUMENT_POSITION_PRECEDING 定数の使用例を示します。 9 * Dom\Text ノードを含む様々なノード間の関係を比較します。 10 */ 11function demonstrateDomNodePositionComparison(): void 12{ 13 // 1. DOM ドキュメントを作成し、サンプルHTMLを読み込みます。 14 $document = new Dom\Document(); 15 $document->loadHTML(' 16 <html> 17 <body> 18 <div id="container"> 19 <p id="first-para">これは最初の段落です。<span id="inner-span">内部要素</span></p> 20 <p id="second-para">そして、次の段落です。</p> 21 </div> 22 </body> 23 </html> 24 '); 25 26 // 2. 比較対象となるノードを取得します。 27 // Dom\Text ノードは直接IDを持たないため、親要素から辿って取得します。 28 $containerDiv = $document->getElementById('container'); 29 $firstParagraph = $document->getElementById('first-para'); 30 $innerSpan = $document->getElementById('inner-span'); 31 $secondParagraph = $document->getElementById('second-para'); 32 33 // firstParagraph の最初の子ノードであるテキストノードを取得します。 34 // "これは最初の段落です。" というテキストを取得することを想定しています。 35 $firstParaTextNode = null; 36 foreach ($firstParagraph->childNodes as $childNode) { 37 if ($childNode instanceof Dom\Text) { 38 $firstParaTextNode = $childNode; 39 break; 40 } 41 } 42 43 echo "--- Dom\Node::DOCUMENT_POSITION_CONTAINED_BY の例 ---\n"; 44 45 // 例1: 子要素が親要素に含まれているか確認します。 46 // innerSpan は firstParagraph に含まれている (CONTAINED_BY) 47 if ($innerSpan && $firstParagraph) { 48 $result = $innerSpan->compareDocumentPosition($firstParagraph); 49 echo "ノード '" . $innerSpan->nodeName . "' とノード '" . $firstParagraph->nodeName . "' の比較:\n"; 50 if ($result & Dom\Node::DOCUMENT_POSITION_CONTAINED_BY) { 51 echo " - '" . $innerSpan->nodeName . "' は '" . $firstParagraph->nodeName . "' に含まれています。\n"; 52 } else { 53 echo " - '" . $innerSpan->nodeName . "' は '" . $firstParagraph->nodeName . "' に含まれていません。\n"; 54 } 55 } 56 57 // 例2: Dom\Text ノードがその親要素に含まれているか確認します。 58 // firstParaTextNode は firstParagraph に含まれている (CONTAINED_BY) 59 if ($firstParaTextNode && $firstParagraph) { 60 $result = $firstParaTextNode->compareDocumentPosition($firstParagraph); 61 echo "テキストノード '" . substr($firstParaTextNode->nodeValue, 0, 15) . "...' とノード '" . $firstParagraph->nodeName . "' の比較:\n"; 62 if ($result & Dom\Node::DOCUMENT_POSITION_CONTAINED_BY) { 63 echo " - テキストノードは '" . $firstParagraph->nodeName . "' に含まれています。\n"; 64 } else { 65 echo " - テキストノードは '" . $firstParagraph->nodeName . "' に含まれていません。\n"; 66 } 67 } 68 69 echo "\n--- Dom\Node::DOCUMENT_POSITION_PRECEDING の例 ---\n"; 70 71 // 例3: 兄弟要素間の先行関係を確認します。 72 // firstParagraph は secondParagraph より先行している (PRECEDING) 73 if ($firstParagraph && $secondParagraph) { 74 $result = $firstParagraph->compareDocumentPosition($secondParagraph); 75 echo "ノード '" . $firstParagraph->nodeName . "' とノード '" . $secondParagraph->nodeName . "' の比較:\n"; 76 if ($result & Dom\Node::DOCUMENT_POSITION_PRECEDING) { 77 echo " - '" . $firstParagraph->nodeName . "' は '" . $secondParagraph->nodeName . "' より先行しています。\n"; 78 } else { 79 echo " - '" . $firstParagraph->nodeName . "' は '" . $secondParagraph->nodeName . "' より先行していません。\n"; 80 } 81 } 82 83 // 例4: 親要素が子要素より先行しているか確認します。 84 // containerDiv は innerSpan を含んでいるため、PRECEDING ではありません。 85 if ($containerDiv && $innerSpan) { 86 $result = $containerDiv->compareDocumentPosition($innerSpan); 87 echo "ノード '" . $containerDiv->nodeName . "' とノード '" . $innerSpan->nodeName . "' の比較:\n"; 88 if ($result & Dom\Node::DOCUMENT_POSITION_PRECEDING) { 89 echo " - '" . $containerDiv->nodeName . "' は '" . $innerSpan->nodeName . "' より先行しています。\n"; 90 } else { 91 echo " - '" . $containerDiv->nodeName . "' は '" . $innerSpan->nodeName . "' より先行していません。\n"; 92 // この場合、実際にはコンテナー要素が内部要素を含んでいる関係になります。 93 if ($result & Dom\Node::DOCUMENT_POSITION_CONTAINS) { 94 echo " - (補足) しかし、'" . $containerDiv->nodeName . "' は '" . $innerSpan->nodeName . "' を含んでいます。\n"; 95 } 96 } 97 } 98} 99 100// サンプル関数の実行 101demonstrateDomNodePositionComparison(); 102
このサンプルコードは、PHPのDOM拡張機能を利用し、HTMLドキュメント内の要素（ノード）が互いにどのような位置関係にあるかをプログラムで確認する方法を示しています。中心となるのはDom\NodeクラスのcompareDocumentPositionメソッドです。このメソッドは、呼び出し元のノード（例えば$nodeA）と引数で指定されたノード（例えば$nodeB）が、ドキュメント内で親子関係、兄弟関係、またはその他の包含関係にあるかを数値（ビットフラグ）として返します。
この戻り値を判定するために、Dom\Node::DOCUMENT_POSITION_CONTAINED_BYのような定数が用いられます。Dom\Node::DOCUMENT_POSITION_CONTAINED_BY定数は、メソッドを呼び出したノードが、比較対象のノードに「含まれている」状態、つまり子孫ノードである場合に返されるビットフラグの一つです。例えば、ある<span>要素が親の<p>要素の中に存在するか、あるいはDom\Textノードがその親要素の中に含まれるかといった関係を調べることができます。
また、キーワードとして挙げられているDom\Node::DOCUMENT_POSITION_PRECEDING定数も同様に、呼び出し元のノードが比較対象のノードより「先行している」（ドキュメントのソース順で先に現れる）状態を示すビットフラグです。サンプルでは、これらの定数を使って、子要素が親要素に含まれるケースや、兄弟要素間でどちらが先に登場するかといった具体的なノード間の位置関係を比較し、その結果を出力しています。これにより、DOMツリー内でのノードの階層や順序をプログラムで正確に把握する方法を学ぶことができます。
このサンプルコードはDOMノード間の位置関係比較を扱いますが、初心者の方はテキストノードがIDを持たないため、親ノードから辿って取得する必要がある点に注意してください。compareDocumentPositionメソッドの戻り値は複数の状態を組み合わせたビットマスクなので、特定の定数と一致するかはビットAND演算子&を使って確認します。Dom\Node::DOCUMENT_POSITION_CONTAINED_BYは「対象ノードが引数のノードに含まれる」ことを示し、DOCUMENT_POSITION_PRECEDINGは「対象ノードが引数のノードより先に現れる」ことを示します。特に、親ノードは子ノードを含みますが、子ノードより先行するわけではないため、DOCUMENT_POSITION_PRECEDINGではない点にご留意ください。ノードが取得できない場合に備え、nullチェックを行うことで予期せぬエラーを防げます。
DOCUMENT_POSITION_CONTAINED_BY でノードの包含関係を調べる
1<?php 2 3// DOMDocumentオブジェクトを新規作成します。 4// HTML構造をプログラムで構築するために使用します。 5$dom = new DOMDocument('1.0', 'UTF-8'); 6$dom->formatOutput = true; // 生成されるXML/HTMLを見やすく整形します。 7 8// ルート要素として <div> を作成し、DOMツリーに追加します。 9$rootElement = $dom->createElement('div'); 10$dom->appendChild($rootElement); 11 12// 子要素として <p> を作成し、<div> 要素に追加します。 13$childElement = $dom->createElement('p'); 14$rootElement->appendChild($childElement); 15 16// テキストノードを作成し、<p> 要素に追加します。 17// これで、<div><p>Hello, DOM!</p></div> という階層構造が完成します。 18$textNode = $dom->createTextNode('Hello, DOM!'); 19$childElement->appendChild($textNode); 20 21echo "構築されたDOM構造:\n"; 22echo $dom->saveXML(); // 構築したDOMツリーをXML形式で表示します。 23echo "\n"; 24 25// Dom\Text::DOCUMENT_POSITION_CONTAINED_BY 定数の使用例 26// この定数は、DOMNode::compareDocumentPosition() メソッドの戻り値に含まれるビットマスクで、 27// あるノードが、比較対象のノードに「含まれている」(contained by) 関係にあることを示します。 28// つまり、「基準ノード」が「比較対象ノード」の子孫である場合にこのフラグが立ちます。 29 30// 例1: テキストノードがp要素に含まれているか？ 31// 基準ノード: $textNode (Hello, DOM!) 32// 比較対象ノード: $childElement (<p>...</p>) 33// $textNode は $childElement の子ノードなので、$childElement に含まれています。 34$position = $textNode->compareDocumentPosition($childElement); 35 36echo "--- 比較結果1 ---\n"; 37echo "テキストノード '{$textNode->nodeValue}' は p要素に「含まれている」か？\n"; 38 39// ビット演算子 '&' を使用して、戻り値の $position に 40// Dom\Text::DOCUMENT_POSITION_CONTAINED_BY フラグがセットされているかを確認します。 41if ($position & Dom\Text::DOCUMENT_POSITION_CONTAINED_BY) { 42 echo "-> はい、テキストノードはp要素に含まれています。\n"; 43} else { 44 echo "-> いいえ、テキストノードはp要素に含まれていません。\n"; 45} 46 47// 例2: p要素がdiv要素に含まれているか？ 48// 基準ノード: $childElement (<p>...</p>) 49// 比較対象ノード: $rootElement (<div>...</div>) 50// $childElement は $rootElement の子ノードなので、$rootElement に含まれています。 51$position = $childElement->compareDocumentPosition($rootElement); 52 53echo "\n--- 比較結果2 ---\n"; 54echo "p要素は div要素に「含まれている」か？\n"; 55 56if ($position & Dom\Text::DOCUMENT_POSITION_CONTAINED_BY) { 57 echo "-> はい、p要素はdiv要素に含まれています。\n"; 58} else { 59 echo "-> いいえ、p要素はdiv要素に含まれていません。\n"; 60} 61 62// 例3: div要素がp要素に含まれているか？ (逆の関係) 63// 基準ノード: $rootElement (<div>...</div>) 64// 比較対象ノード: $childElement (<p>...</p>) 65// <div>は<p>を親としないため、このフラグはセットされません。 66$position = $rootElement->compareDocumentPosition($childElement); 67 68echo "\n--- 比較結果3 ---\n"; 69echo "div要素は p要素に「含まれている」か？\n"; 70 71if ($position & Dom\Text::DOCUMENT_POSITION_CONTAINED_BY) { 72 echo "-> はい、div要素はp要素に含まれています。\n"; 73} else { 74 echo "-> いいえ、div要素はp要素に含まれていません。\n"; 75 // 実際には、この場合 DOCUMENT_POSITION_CONTAINS (基準ノードが比較対象ノードを含んでいる) 76 // または他の関連フラグがセットされる可能性がありますが、 77 // ここでは Dom\Text::DOCUMENT_POSITION_CONTAINED_BY の判定に焦点を当てています。 78} 79 80?>
このサンプルコードは、PHPのDOM操作において、ノード間の階層関係を判定するための定数Dom\Text::DOCUMENT_POSITION_CONTAINED_BYの使い方を説明しています。
まず、DOMDocumentオブジェクトを新規作成し、<div><p>Hello, DOM!</p></div>というシンプルなHTML構造をプログラムで構築します。
Dom\Text::DOCUMENT_POSITION_CONTAINED_BYは、DOMNode::compareDocumentPosition()メソッドの戻り値（int型）に含まれるビットマスク定数です。この定数自体には引数はありません。compareDocumentPosition()メソッドは、比較対象のノードを引数にとり、メソッドを呼び出したノード（基準ノード）と引数のノードの相対的な位置関係を示す整数値を返します。DOCUMENT_POSITION_CONTAINED_BYは、基準ノードが比較対象ノードの「子孫である」（つまり、比較対象ノードに「含まれている」）場合に、その戻り値の整数値に含まれるフラグです。
サンプルコードでは、構築したDOMツリーを使い、テキストノードが<p>要素に含まれているか、また<p>要素が<div>要素に含まれているかを検証しています。これらの比較では、ビット演算子&を用いてDOCUMENT_POSITION_CONTAINED_BYフラグがセットされているかを確認し、「含まれている」という正しい判定結果を得ています。一方、<div>要素が<p>要素に含まれているかという逆の関係を比較する例では、このフラグはセットされないため、「含まれていません」と表示されます。これにより、DOMツリー内のノードが互いにどのような階層関係にあるかをプログラムで正確に判断する方法を理解できます。
この定数は、DOMツリーにおけるノード間の親子関係、特に「基準ノードが比較対象ノードの子孫であるか」、つまり「基準ノードが比較対象ノードに含まれているか」を判定する際に利用します。判定には、DOMNode::compareDocumentPosition()メソッドの戻り値と、ビットAND演算子 & を組み合わせて使う点が重要です。戻り値は複数の状態を示すビットマスクであるため、単純な数値比較ではなく、& 演算子によるフラグの確認が必須となります。
特に注意が必要なのは、この定数が「含まれている」という一方的な関係を示すことです。逆の関係である「含んでいる」（つまり祖先である）かどうかを判定するDOCUMENT_POSITION_CONTAINSとは意味が異なりますので、混同しないよう正確なノード間の位置関係を理解してください。この定数自体がDOMの構造を直接変更するものではなく、ノード間の相対的な関係性を判断するための指標として活用されます。