【PHP8.x】DOMProcessingInstruction::DOCUMENT_POSITION_CONTAINED_BY定数の使い方
DOCUMENT_POSITION_CONTAINED_BY定数の使い方について、初心者にもわかりやすく解説します。
基本的な使い方
『DOCUMENT_POSITION_CONTAINED_BY定数は、DOMドキュメント内における2つのノードの位置関係を示すビットマスク値の一つを表す定数です。この定数は、主にDOMNode::compareDocumentPosition()メソッドの戻り値を評価する際に使用されます。このメソッドは、あるノードが比較対象のノードに対して、ドキュメント内でどのような位置にあるかを判定します。compareDocumentPosition()メソッドの呼び出し元ノードが、引数で渡されたノードによって内包されている場合、つまり呼び出し元ノードが引数のノードの子孫である場合に、戻り値のビットマスクにこの定数のビットが含まれます。例えば、p要素ノードがdiv要素ノードの子要素である場合、p要素ノードのcompareDocumentPosition()メソッドにdiv要素ノードを渡して比較すると、結果にDOCUMENT_POSITION_CONTAINED_BYが含まれます。戻り値は他の状態を示す定数と組み合わされる可能性があるため、特定の状態を確認するには、戻り値とこの定数との間でビット単位のAND演算子（&）を用いて判定するのが一般的です。
構文(syntax)
1<?php 2 3echo DOMProcessingInstruction::DOCUMENT_POSITION_CONTAINED_BY;
引数(parameters)
引数なし
引数はありません
戻り値(return)
int
DOMDocument::loadHTML() などで作成されたDOMProcessingInstructionノードが、他のノードに含まれている状態を表す整数値です。
サンプルコード
DOMノード位置関係を比較する
1<?php 2 3/** 4 * DOMノード間の位置関係を比較し、その結果を人間が読める形式で出力する関数。 5 * 6 * この関数は、DOMツリー内の2つのノードが互いに対してどのような位置関係にあるかを判断するために 7 * DOMNode::compareDocumentPosition() メソッドを使用します。 8 * 主に、ノードが他のノードの前に現れるか (PRECEDING)、後に現れるか (FOLLOWING)、 9 * 含まれているか (CONTAINED_BY)、含むか (CONTAINS) などを確認します。 10 * 11 * @param string $htmlString 比較に使用するHTMLコンテンツ。 12 * @param string $id1 最初のノードのHTML ID属性値。 13 * @param string $id2 2番目のノードのHTML ID属性値。 14 */ 15function compareDomNodePositions(string $htmlString, string $id1, string $id2): void 16{ 17 // DOMDocumentオブジェクトを初期化し、HTMLをロードします。 18 // LIBXML_HTML_NOIMPLIEDとLIBXML_HTML_NODEFDTDフラグは、 19 // 余分な<html>, <body>, <!DOCTYPE html> タグの自動生成を抑制し、 20 // 提供されたHTMLの構造をより正確に保ちます。 21 $dom = new DOMDocument(); 22 $dom->loadHTML($htmlString, LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD); 23 24 // ID属性を使って比較対象のノードを取得します。 25 $node1 = $dom->getElementById($id1); 26 $node2 = $dom->getElementById($id2); 27 28 // ノードが見つからなかった場合はエラーメッセージを表示して終了します。 29 if (!$node1 || !$node2) { 30 echo "エラー: 指定されたID ('{$id1}' または '{$id2}') のノードが見つかりません。\n"; 31 return; 32 } 33 34 echo "--- DOMノードの位置関係比較 ---\n"; 35 echo "ノード1: ID='{$id1}', 要素名='{$node1->nodeName}'\n"; 36 echo "ノード2: ID='{$id2}', 要素名='{$node2->nodeName}'\n\n"; 37 38 // ノード1から見てノード2の位置を比較します。 39 $positionFromNode1 = $node1->compareDocumentPosition($node2); 40 echo "▶ {$id1} (参照ノード) から見て {$id2} (比較対象ノード) の位置:\n"; 41 outputPositionFlags($positionFromNode1); 42 43 echo "\n"; 44 45 // ノード2から見てノード1の位置を比較します。 46 $positionFromNode2 = $node2->compareDocumentPosition($node1); 47 echo "▶ {$id2} (参照ノード) から見て {$id1} (比較対象ノード) の位置:\n"; 48 outputPositionFlags($positionFromNode2); 49} 50 51/** 52 * DOMNode::compareDocumentPosition() メソッドが返すビットマスクフラグを解釈し、 53 * その意味を分かりやすく出力するヘルパー関数。 54 * 55 * @param int $positionFlags compareDocumentPositionメソッドの戻り値（ビットマスク）。 56 */ 57function outputPositionFlags(int $positionFlags): void 58{ 59 // 0はノードが同じであることを示します。 60 if ($positionFlags === 0) { 61 echo " - 同じノードです。\n"; 62 return; 63 } 64 65 // 各フラグをビット論理積 (&) でチェックし、該当する場合に説明を出力します。 66 67 // DOMNode::DOCUMENT_POSITION_DISCONNECTED (0x01) 68 // 比較対象ノードが参照ノードとは異なるサブツリーにあり、直接的な祖先関係も子孫関係もない場合。 69 if (($positionFlags & DOMNode::DOCUMENT_POSITION_DISCONNECTED) > 0) { 70 echo " - DOMツリー上で互いに接続されていません (DISCONNECTED)。\n"; 71 } 72 73 // DOMNode::DOCUMENT_POSITION_PRECEDING (0x02) 74 // 比較対象ノードがDOMツリーの走査順で参照ノードの「前に」現れる場合。 75 // 例: <p id="a"></p><p id="b"></p> の場合、b から見た a は PRECEDING。 76 if (($positionFlags & DOMNode::DOCUMENT_POSITION_PRECEDING) > 0) { 77 echo " - 比較対象ノードは参照ノードのDOMツリー上の「前」にあります (PRECEDING)。\n"; 78 } 79 80 // DOMNode::DOCUMENT_POSITION_FOLLOWING (0x04) 81 // 比較対象ノードがDOMツリーの走査順で参照ノードの「後に」現れる場合。 82 // 例: <p id="a"></p><p id="b"></p> の場合、a から見た b は FOLLOWING。 83 if (($positionFlags & DOMNode::DOCUMENT_POSITION_FOLLOWING) > 0) { 84 echo " - 比較対象ノードは参照ノードのDOMツリー上の「後」にあります (FOLLOWING)。\n"; 85 } 86 87 // DOMNode::DOCUMENT_POSITION_CONTAINS (0x08) 88 // 比較対象ノードが参照ノードを「含む」場合 (参照ノードが比較対象ノードの子孫である場合)。 89 // 例: <div id="parent"><span id="child"></span></div> の場合、parent から見た child は CONTAINS。 90 if (($positionFlags & DOMNode::DOCUMENT_POSITION_CONTAINS) > 0) { 91 echo " - 比較対象ノードは参照ノードを「含んで」います (CONTAINS)。\n"; 92 } 93 94 // DOMNode::DOCUMENT_POSITION_CONTAINED_BY (0x10) 95 // 比較対象ノードが参照ノードに「含まれる」場合 (参照ノードが比較対象ノードの先祖である場合)。 96 // 例: <div id="parent"><span id="child"></span></div> の場合、child から見た parent は CONTAINED_BY。 97 if (($positionFlags & DOMNode::DOCUMENT_POSITION_CONTAINED_BY) > 0) { 98 echo " - 比較対象ノードは参照ノードに「含まれて」います (CONTAINED_BY)。\n"; 99 } 100 101 // DOMNode::DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC (0x20) 102 // DOM実装に固有の理由でノードの位置を特定できない場合。 103 if (($positionFlags & DOMNode::DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) > 0) { 104 echo " - 位置関係が実装固有の方法で決定されます (IMPLEMENTATION_SPECIFIC)。\n"; 105 } 106} 107 108// ------------------------------------------------------------------------------------------ 109// サンプルコードの実行 110// ------------------------------------------------------------------------------------------ 111 112// 比較に使用するHTMLコンテンツ 113$sampleHtml = <<<HTML 114<div id="container"> 115 <p id="firstParagraph">最初の段落です。</p> 116 <div id="innerDiv"> 117 <span id="innerSpan">内部のスパンです。</span> 118 </div> 119 <p id="secondParagraph">二番目の段落です。</p> 120</div> 121HTML; 122 123echo "=================================================\n"; 124echo " ケース1: 兄弟ノードの比較 \n"; 125echo " (secondParagraph は firstParagraph の後に現れる) \n"; 126echo "=================================================\n"; 127// firstParagraph と secondParagraph は同じ階層の兄弟ノードです。 128// secondParagraph は firstParagraph の後にDOMツリーに現れます。 129compareDomNodePositions($sampleHtml, "firstParagraph", "secondParagraph"); 130 131echo "\n=================================================\n"; 132echo " ケース2: 親子ノードの比較 \n"; 133echo " (innerSpan は container に含まれ、container は innerSpan を含む) \n"; 134echo "=================================================\n"; 135// container は innerSpan の親要素です。 136// innerSpan は container に含まれています。 137compareDomNodePositions($sampleHtml, "container", "innerSpan"); 138 139echo "\n=================================================\n"; 140echo " ケース3: 共通の祖先を持つノードの比較 \n"; 141echo " (innerSpan は firstParagraph の後に現れる) \n"; 142echo "=================================================\n"; 143// firstParagraph と innerSpan は直接の親子でも兄弟でもありませんが、 144// 共通の祖先 (container) を持ち、DOMツリー上での前後関係があります。 145compareDomNodePositions($sampleHtml, "firstParagraph", "innerSpan"); 146 147?>
PHP 8のDOMNode::DOCUMENT_POSITION_CONTAINED_BY定数は、DOMツリー上の二つのノード間の位置関係を判断する際に用いられる整数値（ビットフラグ）の一つです。この定数自体に引数はなく、戻り値は整数型です。これは主にDOMNode::compareDocumentPosition()メソッドの戻り値として使われます。このメソッドは、指定されたノードが参照ノードに対してどのような位置にあるかを示すビットマスクを整数値で返します。
具体的にDOCUMENT_POSITION_CONTAINED_BYが示すのは、「比較対象のノードが参照ノードに『含まれている』」という関係です。言い換えれば、参照ノードが比較対象ノードの先祖である場合に、このフラグがセットされた戻り値が得られます。例えば、親要素から子要素を比較する場合にこの関係が当てはまります。
この定数以外にも、compareDocumentPosition()メソッドの戻り値には、ノードが互いに接続されていないことを示すDOCUMENT_POSITION_DISCONNECTED、参照ノードの前に現れるDOCUMENT_POSITION_PRECEDING、後に現れるDOCUMENT_POSITION_FOLLOWING、参照ノードが比較対象ノードを「含む」関係を示すDOCUMENT_POSITION_CONTAINSなど、様々なビットフラグが含まれることがあります。
サンプルコードでは、compareDomNodePositions関数が二つのHTMLノードIDを受け取り、DOMNode::compareDocumentPosition()を使ってそれらの位置関係を詳細に比較し、その結果をoutputPositionFlags関数で人間が読みやすい形式で出力しています。特に「ケース2: 親子ノードの比較」では、親ノードであるcontainerから子ノードのinnerSpanを比較する際にDOCUMENT_POSITION_CONTAINSが、逆にinnerSpanからcontainerを比較する際にDOCUMENT_POSITION_CONTAINED_BYが検出され、ノード間の包含関係が正確に示されていることが分かります。これにより、プログラムでDOM構造を詳細に分析することが可能になります。
このサンプルコードは、PHPのDOMNode::compareDocumentPosition()メソッドを使ったノード間の位置関係比較を示しています。メソッドの戻り値は、複数の状態を組み合わせたビットマスク（数値）です。DOMNode::DOCUMENT_POSITION_CONTAINED_BY や DOMNode::DOCUMENT_POSITION_PRECEDING といった各定数が示す意味を理解し、ビット論理積(&)演算子を使って個々の状態を判定する必要があります。比較を行う際は、$ノードA->compareDocumentPosition($ノードB) のように、どちらのノードが「参照元」で、どちらが「比較対象」なのかを常に意識してください。結果は参照元から見た比較対象の位置を示します。また、比較結果はHTMLのDOMツリー構造に強く依存するため、対象のHTMLがどのように構成されているかを事前に把握しておくことが、結果を正しく解釈する上で非常に重要です。
DOMノードの包含関係を比較する
1<?php 2 3/** 4 * DOMNode::compareDocumentPosition メソッドと DOMProcessingInstruction::DOCUMENT_POSITION_CONTAINED_BY 定数を使用して、 5 * ノード間の包含関係を比較する例を示します。 6 * 7 * DOMProcessingInstruction::DOCUMENT_POSITION_CONTAINED_BY は、比較対象のノード（レシーバー）が 8 * 引数として渡されたノードに含まれている場合に、compareDocumentPosition メソッドの戻り値に含まれるビットマスク定数です。 9 * 10 * PHPのリファレンス情報ではこの定数が DOMProcessingInstruction に所属するとされていますが、 11 * 実際には DOMNode クラスで定義され、DOMProcessingInstruction は DOMNode を継承しているためアクセス可能です。 12 * このサンプルでは、リファレンス情報に沿って DOMProcessingInstruction:: を使用します。 13 */ 14function demonstrateDomPositionComparison(): void 15{ 16 // 1. DOMDocument を作成し、XML ヘッダと整形を有効にする 17 $dom = new DOMDocument('1.0', 'UTF-8'); 18 $dom->formatOutput = true; 19 20 // 2. ルート要素を作成し、DOMに追加 21 $root = $dom->createElement('root'); 22 $dom->appendChild($root); 23 24 // 3. 処理命令 (Processing Instruction) ノードを作成 25 // リファレンス情報で「所属クラス: DOMProcessingInstruction」と指定されているため、 26 // DOMProcessingInstruction のインスタンスを生成・操作します。 27 $processingInstruction = $dom->createProcessingInstruction('php', 'echo "Hello from PI!";'); 28 29 // 4. 処理命令ノードをルート要素の子として追加 30 // これにより、$processingInstruction は $root に「含まれる」関係になります。 31 $root->appendChild($processingInstruction); 32 33 // 5. 別の要素ノードを作成し、ルート要素の子として追加 (処理命令ノードとは兄弟関係) 34 $childElement = $dom->createElement('child'); 35 $root->appendChild($childElement); 36 37 // 生成されたDOMツリーを表示し、構造を視覚的に確認 38 echo "--- 生成されたDOMツリー ---\n"; 39 echo $dom->saveXML() . "\n"; 40 echo "--------------------------\n\n"; 41 42 echo "DOMノード間の位置関係を比較します。\n\n"; 43 44 // シナリオ 1: 処理命令ノード ($processingInstruction) がルート要素 ($root) に含まれているか？ 45 // 期待される結果: はい 46 echo "シナリオ 1: 処理命令ノードがルート要素に含まれているか？\n"; 47 $positionFlags = $processingInstruction->compareDocumentPosition($root); 48 49 // compareDocumentPosition の戻り値と DOCUMENT_POSITION_CONTAINED_BY をビット論理積 (&) で比較 50 // 結果が定数と同じであれば、その関係性が存在します。 51 if (($positionFlags & DOMProcessingInstruction::DOCUMENT_POSITION_CONTAINED_BY) === DOMProcessingInstruction::DOCUMENT_POSITION_CONTAINED_BY) { 52 echo " 結果: はい、処理命令ノードはルート要素に含まれています。\n\n"; 53 } else { 54 echo " 結果: いいえ、処理命令ノードはルート要素に含まれていません。\n\n"; 55 } 56 57 // シナリオ 2: ルート要素 ($root) が処理命令ノード ($processingInstruction) を含んでいるか？ 58 // (これは DOCUMENT_POSITION_CONTAINED_BY の逆の関係性である DOCUMENT_POSITION_CONTAINS を使用します) 59 // 期待される結果: はい 60 echo "シナリオ 2: ルート要素が処理命令ノードを含んでいるか？\n"; 61 $positionFlags = $root->compareDocumentPosition($processingInstruction); 62 63 // DOCUMENT_POSITION_CONTAINS は DOMNode クラスの定数です。 64 if (($positionFlags & DOMNode::DOCUMENT_POSITION_CONTAINS) === DOMNode::DOCUMENT_POSITION_CONTAINS) { 65 echo " 結果: はい、ルート要素は処理命令ノードを含んでいます。\n\n"; 66 } else { 67 echo " 結果: いいえ、ルート要素は処理命令ノードを含んでいません。\n\n"; 68 } 69 70 // シナリオ 3: 処理命令ノード ($processingInstruction) が子要素 ($childElement) に含まれているか？ 71 // (両者は兄弟関係にあるため、包含関係にはありません) 72 // 期待される結果: いいえ 73 echo "シナリオ 3: 処理命令ノードが子要素に含まれているか？\n"; 74 $positionFlags = $processingInstruction->compareDocumentPosition($childElement); 75 76 if (($positionFlags & DOMProcessingInstruction::DOCUMENT_POSITION_CONTAINED_BY) === DOMProcessingInstruction::DOCUMENT_POSITION_CONTAINED_BY) { 77 echo " 結果: はい、処理命令ノードは子要素に含まれています。\n\n"; 78 } else { 79 echo " 結果: いいえ、処理命令ノードは子要素に含まれていません。（両者は兄弟関係です）\n\n"; 80 } 81} 82 83// サンプル関数を実行 84demonstrateDomPositionComparison(); 85
DOMProcessingInstruction::DOCUMENT_POSITION_CONTAINED_BY は、XMLやHTML文書の構造（DOMツリー）において、ノード間の位置関係を判定するための定数です。この定数自体には引数はなく、整数型のビットマスク値として定義されています。主に DOMNode クラスの compareDocumentPosition メソッドと組み合わせて使用されます。
compareDocumentPosition メソッドは、呼び出し元のノード（レシーバー）と引数に渡されたノードの位置関係を示す整数値（ビットマスク）を返します。この戻り値と DOCUMENT_POSITION_CONTAINED_BY 定数をビット論理積（&）で比較することで、レシーバーノードが引数ノードに「含まれている」かどうかを判別できます。もし含まれている場合、比較結果は DOCUMENT_POSITION_CONTAINED_BY と一致します。
PHPのリファレンスではこの定数が DOMProcessingInstruction クラスに所属するとされていますが、実態としては DOMNode クラスで定義されており、DOMProcessingInstruction が DOMNode を継承しているためアクセス可能です。サンプルコードでは、この情報に沿って DOMProcessingInstruction:: を使用しています。
サンプルコードでは、DOMDocument を用いてXML構造を作成し、処理命令ノードがルート要素に含まれているか、あるいは兄弟ノードに含まれていないかといった、複数のシナリオでノード間の包含関係を具体的に比較し、この定数の使い方と判定結果を示しています。
この定数DOCUMENT_POSITION_CONTAINED_BYは、DOMNode::compareDocumentPositionメソッドの戻り値（ビットマスク）と比較して使用します。単独で意味を持つものではなく、ビット論理積演算子&で正しく比較してください。リファレンスではDOMProcessingInstructionに所属すると記載されていますが、実際には基底クラスであるDOMNodeで定義されている定数です。DOMNodeを継承するすべてのDOMノードクラスからアクセスできますので、コードの読みやすさを考慮し、DOMNode::で参照することも検討してください。この定数は、比較元のノードが引数のノードに「含まれる」関係を示します。もし「引数のノードが比較元のノードを含む」関係を調べたい場合は、DOMNode::DOCUMENT_POSITION_CONTAINSという別の定数を使用する必要があることに注意してください。DOMツリーの親子関係や包含関係を正しく理解することが、これらの定数を適切に利用する上で重要です。