【PHP8.x】DOMDocument::DOCUMENT_POSITION_CONTAINED_BY定数の使い方
DOCUMENT_POSITION_CONTAINED_BY定数の使い方について、初心者にもわかりやすく解説します。
基本的な使い方
DOCUMENT_POSITION_CONTAINED_BY定数は、DOMツリーにおける二つのノード間の相対的な位置関係を示す値を表す定数です。この定数は、PHPのDOM拡張機能で提供される DOMNode::compareDocumentPosition() メソッドの戻り値として利用されます。DOMDocument オブジェクトも DOMNode インターフェースを実装しているため、そのインスタンスを通じてノードの比較を行う際にこの定数を参照します。
DOMNode::compareDocumentPosition() メソッドは、比較元ノードが比較対象ノードに対してどのような位置関係にあるかを示すビットマスクを返します。DOCUMENT_POSITION_CONTAINED_BY 定数は、比較元ノードが比較対象ノードを含んでいる場合、すなわち比較対象ノードが比較元ノードの子孫であるか、または比較元ノード自身である場合に、その戻り値に含まれるビットフラグの一つです。開発者はこの定数を使って、compareDocumentPosition() メソッドの戻り値とビット論理積（AND）演算を行うことで、特定の包含関係を効率的に判定できます。
この定数を活用することで、ウェブページのDOM構造を解析し、特定の要素が別の要素の内部に存在するかどうかをプログラムで正確に判断することが可能になります。これにより、複雑なDOM操作や要素の探索において、ノード間の親子関係や包含関係に基づいたロジックを簡潔に記述できるようになります。
構文(syntax)
1<?php 2$document = new DOMDocument(); 3$parentElement = $document->createElement('parent'); 4$childElement = $document->createElement('child'); 5$parentElement->appendChild($childElement); 6$document->appendChild($parentElement); 7 8($childElement->compareDocumentPosition($parentElement) & DOCUMENT_POSITION_CONTAINED_BY);
引数(parameters)
引数なし
引数はありません
戻り値(return)
int
DOMDocument::DOCUMENT_POSITION_CONTAINED_BYは、あるノードが別のノードに含まれていることを示す整数値1を返します。
サンプルコード
DOMノードの位置関係を比較する
1<?php 2 3/** 4 * DOMNode::compareDocumentPosition メソッドを使用して、 5 * 2つのDOMノード間の相対的な位置関係を比較するサンプルコードです。 6 * 7 * 特に、キーワードである DOMNode::DOCUMENT_POSITION_PRECEDING と、 8 * リファレンス情報にある DOMNode::DOCUMENT_POSITION_CONTAINED_BY 定数の意味を 9 * 理解することに焦点を当てています。 10 */ 11function demonstrateDomNodePositionComparison(): void 12{ 13 // 1. DOMDocument オブジェクトを作成し、シンプルなHTMLコンテンツを読み込みます。 14 $dom = new DOMDocument(); 15 // HTMLのパースエラーを抑制します。実際のアプリケーションでは適切なエラーハンドリングを推奨します。 16 @$dom->loadHTML(' 17 <html> 18 <body> 19 <div id="parentDiv"> 20 <p id="firstParagraph">最初の段落です。</p> 21 <span id="targetSpan">ターゲットの<span>要素</span>です。</span> 22 <p id="secondParagraph">二番目の段落です。</p> 23 </div> 24 </body> 25 </html> 26 '); 27 28 // 2. 比較に使用するDOMノードをIDで取得します。 29 // getElementById は DOMElement を返すため、DOMNodeとして扱えます。 30 $parentDivNode = $dom->getElementById('parentDiv'); 31 $firstParagraphNode = $dom->getElementById('firstParagraph'); 32 $targetSpanNode = $dom->getElementById('targetSpan'); 33 $secondParagraphNode = $dom->getElementById('secondParagraph'); 34 35 echo "--- ノードの位置関係比較のデモンストレーション ---\n\n"; 36 37 // --- 比較例 1: targetSpan と firstParagraph --- 38 // targetSpan の視点から見て firstParagraph がどこにあるかを比較します。 39 // firstParagraph は targetSpan の "前" に位置します。 40 echo "■ 比較: targetSpan と firstParagraph\n"; 41 $position1 = $targetSpanNode->compareDocumentPosition($firstParagraphNode); 42 echo " - 結果のビットマスク値: " . $position1 . "\n"; 43 44 // DOCUMENT_POSITION_PRECEDING は、比較対象のノードが、呼び出し元のノードの 45 // 前に位置する場合にセットされます。 46 if (($position1 & DOMNode::DOCUMENT_POSITION_PRECEDING) !== 0) { 47 echo " - [✓] " . "DOMNode::DOCUMENT_POSITION_PRECEDING: targetSpan の " 48 . "前方に firstParagraph が位置します。\n"; 49 } 50 if (($position1 & DOMNode::DOCUMENT_POSITION_FOLLOWING) !== 0) { 51 echo " - [ ] " . "DOMNode::DOCUMENT_POSITION_FOLLOWING: targetSpan の " 52 . "後方に firstParagraph が位置します。\n"; 53 } 54 if (($position1 & DOMNode::DOCUMENT_POSITION_CONTAINED_BY) !== 0) { 55 echo " - [ ] " . "DOMNode::DOCUMENT_POSITION_CONTAINED_BY: targetSpan が " 56 . "firstParagraph に包含されています。\n"; 57 } 58 if (($position1 & DOMNode::DOCUMENT_POSITION_CONTAINS) !== 0) { 59 echo " - [ ] " . "DOMNode::DOCUMENT_POSITION_CONTAINS: targetSpan が " 60 . "firstParagraph を包含しています。\n"; 61 } 62 if (($position1 & DOMNode::DOCUMENT_POSITION_DISCONNECTED) !== 0) { 63 echo " - [ ] " . "DOMNode::DOCUMENT_POSITION_DISCONNECTED: ノードが接続されていません。\n"; 64 } 65 echo "\n"; 66 67 // --- 比較例 2: targetSpan と parentDiv --- 68 // targetSpan の視点から見て parentDiv がどこにあるかを比較します。 69 // targetSpan は parentDiv に "包含されて" います。 70 echo "■ 比較: targetSpan と parentDiv\n"; 71 $position2 = $targetSpanNode->compareDocumentPosition($parentDivNode); 72 echo " - 結果のビットマスク値: " . $position2 . "\n"; 73 74 // DOCUMENT_POSITION_CONTAINED_BY は、呼び出し元のノードが、比較対象のノードに 75 // 包含されている場合にセットされます。 76 if (($position2 & DOMNode::DOCUMENT_POSITION_CONTAINED_BY) !== 0) { 77 echo " - [✓] " . "DOMNode::DOCUMENT_POSITION_CONTAINED_BY: targetSpan が " 78 . "parentDiv に包含されています。\n"; 79 } 80 if (($position2 & DOMNode::DOCUMENT_POSITION_CONTAINS) !== 0) { 81 echo " - [ ] " . "DOMNode::DOCUMENT_POSITION_CONTAINS: targetSpan が " 82 . "parentDiv を包含しています。\n"; 83 } 84 if (($position2 & DOMNode::DOCUMENT_POSITION_PRECEDING) !== 0) { 85 echo " - [✓] " . "DOMNode::DOCUMENT_POSITION_PRECEDING: targetSpan の " 86 . "前方に parentDiv が位置します (親は子の前に来るため)。\n"; 87 } 88 if (($position2 & DOMNode::DOCUMENT_POSITION_FOLLOWING) !== 0) { 89 echo " - [ ] " . "DOMNode::DOCUMENT_POSITION_FOLLOWING: targetSpan の " 90 . "後方に parentDiv が位置します。\n"; 91 } 92 echo "\n"; 93 94 // --- 比較例 3: parentDiv と targetSpan --- 95 // parentDiv の視点から見て targetSpan がどこにあるかを比較します。 96 // parentDiv は targetSpan を "包含して" います。 97 echo "■ 比較: parentDiv と targetSpan\n"; 98 $position3 = $parentDivNode->compareDocumentPosition($targetSpanNode); 99 echo " - 結果のビットマスク値: " . $position3 . "\n"; 100 101 // DOCUMENT_POSITION_CONTAINS は、呼び出し元のノードが、比較対象のノードを 102 // 包含している場合にセットされます。 103 if (($position3 & DOMNode::DOCUMENT_POSITION_CONTAINS) !== 0) { 104 echo " - [✓] " . "DOMNode::DOCUMENT_POSITION_CONTAINS: parentDiv が " 105 . "targetSpan を包含しています。\n"; 106 } 107 if (($position3 & DOMNode::DOCUMENT_POSITION_CONTAINED_BY) !== 0) { 108 echo " - [ ] " . "DOMNode::DOCUMENT_POSITION_CONTAINED_BY: parentDiv が " 109 . "targetSpan に包含されています。\n"; 110 } 111 if (($position3 & DOMNode::DOCUMENT_POSITION_FOLLOWING) !== 0) { 112 echo " - [✓] " . "DOMNode::DOCUMENT_POSITION_FOLLOWING: parentDiv の " 113 . "後方に targetSpan が位置します (子は親の後に来るため)。\n"; 114 } 115 if (($position3 & DOMNode::DOCUMENT_POSITION_PRECEDING) !== 0) { 116 echo " - [ ] " . "DOMNode::DOCUMENT_POSITION_PRECEDING: parentDiv の " 117 . "前方に targetSpan が位置します。\n"; 118 } 119 echo "\n"; 120} 121 122// 関数を実行して結果を表示します。 123demonstrateDomNodePositionComparison();
このPHPサンプルコードは、DOMNode::compareDocumentPositionメソッドを使用して、ウェブページの要素であるDOMノード同士がどのような相対的な位置関係にあるかを比較する方法を説明しています。このメソッドは、呼び出し元のノードと、引数として渡されたノードの相対的な位置を調べ、その結果を複数の状態を同時に表す整数値のビットマスクとして返します。
特に、DOMNode::DOCUMENT_POSITION_CONTAINED_BYとDOMNode::DOCUMENT_POSITION_PRECEDINGという二つの定数の意味を学ぶことができます。DOMNode::DOCUMENT_POSITION_CONTAINED_BYは、呼び出し元のノードが、比較対象のノードに「包含されている」（その子孫である）場合に結果のビットマスクに含まれます。例えば、子ノードが親ノードと比較された際にこの状態が検出されます。一方、DOMNode::DOCUMENT_POSITION_PRECEDINGは、比較対象のノードが、呼び出し元のノードよりもドキュメントツリー上で「前方」に位置する場合にセットされます。これは、兄弟ノード間で先に現れるノードと比較する際などに確認できます。
サンプルコードでは、まず簡単なHTMLコンテンツを読み込み、特定のDOMノードを取得しています。その後、異なるノードの組み合わせに対してcompareDocumentPositionメソッドを適用し、戻り値のビットマスクを論理AND演算子（&）で各定数と比較することで、それぞれの位置関係がどのように検出されるかを出力しています。これにより、ノードが親子関係や兄弟関係においてどのような位置にあるかを正確に判断できるようになります。
このサンプルコードを利用する際の注意点として、まずDOMNode::compareDocumentPosition メソッドの戻り値はビットマスクであるため、複数の状態が同時に真となる可能性があります。特定の定数と一致するか確認するには、== ではなく & (ビットAND演算子) を使用して比較するようにしてください。初心者が間違いやすい点ですので特に注意が必要です。
また、DOMNode::DOCUMENT_POSITION_PRECEDING や DOMNode::DOCUMENT_POSITION_FOLLOWING は、ノードがHTML文書内で物理的に前か後ろにあるかを示します。親ノードは常に子ノードの前に、子ノードは親ノードの後に位置すると解釈されます。
サンプルコード内の@演算子はエラー出力を抑制しますが、これは開発時の一時的な使用にとどめ、本番環境では使用を避けてください。HTMLのパースエラーなどは、ノードの取得失敗や予期せぬDOM構造に繋がりかねません。安全なコード運用のため、try-catchなどの適切なエラーハンドリングを実装することが推奨されます。
PHP DOMノード包含関係の判定
1<?php 2 3/** 4 * DOMノード間の位置関係を比較し、DOMNode::DOCUMENT_POSITION_CONTAINED_BY 定数の使用方法を示す関数。 5 * 6 * DOMNode::compareDocumentPosition() メソッドは、呼び出し元のノードと引数で指定されたノードの 7 * 相対的な位置関係を示す整数（ビットマスク）を返します。 8 * DOMNode::DOCUMENT_POSITION_CONTAINED_BY 定数は、比較対象のノードが呼び出し元のノードに含まれている 9 * （つまり、比較対象ノードが呼び出し元ノードの先祖である）場合に、結果のビットマスクに含まれる値です。 10 * 11 * このサンプルでは、特定のノードが別のノードの「内部に含まれる」関係にあるかを判定します。 12 */ 13function demonstrateDomPositionContainedBy(): void 14{ 15 // 1. 新しいDOMDocumentインスタンスを作成 16 $dom = new DOMDocument('1.0', 'UTF-8'); 17 $dom->formatOutput = true; // 出力整形を有効にし、見やすくします 18 19 // 2. ルート要素 'root' を作成し、DOMに追加 20 $rootElement = $dom->createElement('root'); 21 $dom->appendChild($rootElement); 22 23 // 3. 子要素 'parent' を作成し、'root' の子として追加 24 $parentElement = $dom->createElement('parent'); 25 $rootElement->appendChild($parentElement); 26 27 // 4. 孫要素 'child' を作成し、'parent' の子として追加 28 $childElement = $dom->createElement('child'); 29 $parentElement->appendChild($childElement); 30 31 echo "=== DOMNode::compareDocumentPosition() と DOMNode::DOCUMENT_POSITION_CONTAINED_BY の使用例 ===\n\n"; 32 33 // ケース1: childElement が parentElement に含まれているかを確認 34 // childElement (呼び出し元) は parentElement (引数) に含まれている（子孫である）ので、 35 // DOMNode::DOCUMENT_POSITION_CONTAINED_BY フラグがセットされるはずです。 36 $positionChildVsParent = $childElement->compareDocumentPosition($parentElement); 37 38 echo "比較: childElement->compareDocumentPosition(parentElement)\n"; 39 echo "比較結果の生の値: " . $positionChildVsParent . "\n"; 40 41 // 結果が DOMNode::DOCUMENT_POSITION_CONTAINED_BY を含んでいるかビット論理積でチェック 42 if (($positionChildVsParent & DOMNode::DOCUMENT_POSITION_CONTAINED_BY) === DOMNode::DOCUMENT_POSITION_CONTAINED_BY) { 43 echo "-> 結果: childElement は parentElement に含まれています (childElement は parentElement の子孫です)。\n"; 44 } else { 45 echo "-> 結果: childElement は parentElement に含まれていません。\n"; 46 } 47 48 echo "\n----------------------------------------\n\n"; 49 50 // ケース2: rootElement が parentElement に含まれているかを確認 51 // rootElement (呼び出し元) は parentElement (引数) を含んでいますが、 52 // parentElement に含まれているわけではない（先祖である）ので、 53 // DOMNode::DOCUMENT_POSITION_CONTAINED_BY フラグはセットされないはずです。 54 $positionRootVsParent = $rootElement->compareDocumentPosition($parentElement); 55 56 echo "比較: rootElement->compareDocumentPosition(parentElement)\n"; 57 echo "比較結果の生の値: " . $positionRootVsParent . "\n"; 58 59 if (($positionRootVsParent & DOMNode::DOCUMENT_POSITION_CONTAINED_BY) === DOMNode::DOCUMENT_POSITION_CONTAINED_BY) { 60 echo "-> 結果: rootElement は parentElement に含まれています。\n"; 61 } else { 62 echo "-> 結果: rootElement は parentElement に含まれていません (実際には、rootElement は parentElement の先祖です)。\n"; 63 } 64} 65 66// 関数を実行して動作を確認します 67demonstrateDomPositionContainedBy();
PHPのDOMNode::DOCUMENT_POSITION_CONTAINED_BY定数は、DOMツリーにおいて、あるノードが別のノードに「含まれている」（つまり、子孫である）状態を示す整数値です。この定数は、主にDOMNode::compareDocumentPosition()メソッドの戻り値を解析する際に利用されます。compareDocumentPosition()メソッドは、呼び出し元のノードと引数で指定されたノードの相対的な位置関係をビットマスクとして返します。
サンプルコードでは、root、parent、childという親子関係を持つDOM構造を作成し、ノード間の包含関係を検証しています。最初の比較では、childElementがparentElementに「含まれている」かを確認します。childElementはparentElementの子孫であるため、compareDocumentPosition()の結果にはDOCUMENT_POSITION_CONTAINED_BYフラグが含まれ、「含まれている」と正しく判断されます。
次に、rootElementがparentElementに「含まれている」かを検証します。rootElementはparentElementの先祖であり、含まれる関係ではないため、このフラグは結果に含まれず、「含まれていない」と判断されます。このように、この定数とビット論理積 (&) を組み合わせることで、DOMツリー内のノードの親子関係や包含関係を正確に判定することが可能です。
DOMNode::DOCUMENT_POSITION_CONTAINED_BY 定数は、呼び出し元のノードが比較対象のノード（引数）の子孫である場合に、compareDocumentPosition メソッドの戻り値のビットマスクに含まれる値を示します。定数名と「どちらがどちらに含まれるか」の関係を混同しやすいので、正確な意味を理解することが重要です。
compareDocumentPosition メソッドの戻り値は、複数の状態を示すビットマスクですので、特定の状態を確認する際には、ビット論理積演算子 & を用いて比較する必要があります。この仕組みは、DOMツリー内でのノード間の厳密な位置関係をプログラムで判定する際に役立ちます。実際の開発では、比較対象のノードが存在しない場合なども考慮し、堅牢なコードを記述することを推奨します。