【PHP8.x】DOMDocumentFragment::DOCUMENT_POSITION_CONTAINS定数の使い方

DOCUMENT_POSITION_CONTAINS定数の使い方について、初心者にもわかりやすく解説します。

作成日: 2025年09月11日更新日: 2025年10月31日

基本的な使い方

DOCUMENT_POSITION_CONTAINS定数は、PHPのDOM拡張機能において、DOMツリー内のノード間で、あるノードが別のノードを包含している関係を表す定数です。この定数は、主にDOMNodeクラス（DOMDocumentFragmentクラスもDOMNodeを継承しています）が提供するcompareDocumentPosition()メソッドの戻り値として利用されます。

compareDocumentPosition()メソッドは、二つのノード間の相対的な位置関係を比較し、その結果をビットマスク形式の整数値として返します。DOCUMENT_POSITION_CONTAINS定数は、この比較において、比較対象となるノードが、基準となるノードをその子孫ノードとして「含んでいる」状態を示します。例えば、ある親ノードと子ノードを比較する際に、親ノード側が子ノードを包含している関係であれば、この定数の値が比較結果に含まれることになります。

この定数は、開発者がDOMツリー内の要素の親子関係や祖先・子孫関係をプログラムで効率的に判断するために重要な役割を果たします。特定の要素が別の要素の内部に存在するかどうか、つまり一方の要素がもう一方の要素のコンテナであるかどうかを確認する際などに、この定数を用いて判断することが可能です。DOM操作において複雑なツリー構造の関係性を簡潔に把握し、適切な処理を行うために役立ちます。

構文(syntax)


1<?php
2
3echo DOMDocumentFragment::DOCUMENT_POSITION_CONTAINS;
4
5?>

引数(parameters)

引数なし

引数はありません

戻り値(return)

int

DOMDocumentFragment::DOCUMENT_POSITION_CONTAINS は、ノードが別のノードを完全に包含していることを示す整数値を返します。

サンプルコード

PHP DOMノード包含関係を調べる


1<?php
2
3/**
4 * DOMDocumentFragment::DOCUMENT_POSITION_CONTAINS 定数の使用例を示すサンプルコード。
5 *
6 * この定数は、DOMNode::compareDocumentPosition() メソッドの結果を解析する際に使用され、
7 * あるノードが別のノードを含んでいるかどうかを判断するのに役立ちます。
8 * compareDocumentPosition() はビットマスクを返すため、ビット論理AND演算子 (&) を使って定数と比較します。
9 *
10 * PHP 8 環境で実行可能です。
11 */
12
13// 1. DOMDocument オブジェクトを作成し、HTMLコンテンツをロードします。
14$dom = new DOMDocument();
15// loadHTML() は非HTML5の警告を出すことがあるため、@ を付けて抑制するか、
16// LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD などのオプションで対応することもできます。
17// 今回は簡潔さのため、基本形を使用します。
18$htmlContent = '
19<html>
20<body>
21    <div id="parent-element">
22        <p id="child-element">これは子要素です。</p>
23    </div>
24    <span id="sibling-element">これは兄弟要素です。</span>
25</body>
26</html>';
27$dom->loadHTML($htmlContent);
28
29// 2. 比較対象となるノードをIDで取得します。
30// getElementById() は DOMElement オブジェクトを返します。
31$parentElement = $dom->getElementById('parent-element');
32$childElement = $dom->getElementById('child-element');
33$siblingElement = $dom->getElementById('sibling-element');
34
35echo "--- DOM ノード位置比較のデモンストレーション ---\n\n";
36
37// 3. DOCUMENT_POSITION_CONTAINS 定数の値を確認します。
38// この定数は DOMDocumentFragment クラスに属しますが、DOMNode の比較結果で利用します。
39echo "DOCUMENT_POSITION_CONTAINS 定数の値: " . DOMDocumentFragment::DOCUMENT_POSITION_CONTAINS . "\n\n";
40
41// 4. 親ノードと子ノードの位置関係を比較します。
42if ($parentElement && $childElement) {
43    echo "比較対象: 親要素 (id='parent-element') と 子要素 (id='child-element')\n";
44    // compareDocumentPosition() は、現在のノード (parentElement) が引数のノード (childElement)
45    // に対してどのような位置関係にあるかを示すビットマスクを返します。
46    $position = $parentElement->compareDocumentPosition($childElement);
47    echo "compareDocumentPosition() の戻り値 (ビットマスク): " . $position . "\n";
48
49    // DOCUMENT_POSITION_CONTAINS は、参照ノードが比較対象ノードを含んでいる場合に
50    // 戻り値のビットマスクに含まれます。
51    if ($position & DOMDocumentFragment::DOCUMENT_POSITION_CONTAINS) {
52        echo "結果: 'parent-element' は 'child-element' を含んでいます。\n";
53    } else {
54        echo "結果: 'parent-element' は 'child-element' を含んでいません。\n";
55    }
56
57    // 逆に、DOCUMENT_POSITION_CONTAINED_BY は、参照ノードが比較対象ノードに含まれている場合に
58    // 戻り値のビットマスクに含まれます。
59    if ($position & DOMDocumentFragment::DOCUMENT_POSITION_CONTAINED_BY) {
60        echo "結果補足: 'parent-element' は 'child-element' に含まれています (これは誤った結果です)。\n";
61    } else {
62        echo "結果補足: 'parent-element' は 'child-element' に含まれていません。\n";
63    }
64    echo "\n";
65} else {
66    echo "エラー: 'parent-element' または 'child-element' が見つかりませんでした。\n\n";
67}
68
69// 5. 兄弟ノード間の位置関係を比較します。
70if ($parentElement && $siblingElement) {
71    echo "比較対象: 親要素 (id='parent-element') と 兄弟要素 (id='sibling-element')\n";
72    $position = $parentElement->compareDocumentPosition($siblingElement);
73    echo "compareDocumentPosition() の戻り値 (ビットマスク): " . $position . "\n";
74
75    // 親要素が兄弟要素を含んでいるかチェックします。
76    if ($position & DOMDocumentFragment::DOCUMENT_POSITION_CONTAINS) {
77        echo "結果: 'parent-element' は 'sibling-element' を含んでいます。(このケースでは偽となります)\n";
78    } else {
79        echo "結果: 'parent-element' は 'sibling-element' を含んでいません。(正しい結果)\n";
80    }
81    echo "\n";
82} else {
83    echo "エラー: 'parent-element' または 'sibling-element' が見つかりませんでした。\n\n";
84}
85
86// 6. 異なる階層のノードを比較します (例: 子要素と兄弟要素)。
87if ($childElement && $siblingElement) {
88    echo "比較対象: 子要素 (id='child-element') と 兄弟要素 (id='sibling-element')\n";
89    $position = $childElement->compareDocumentPosition($siblingElement);
90    echo "compareDocumentPosition() の戻り値 (ビットマスク): " . $position . "\n";
91
92    // 子要素が兄弟要素を含んでいるかチェックします。
93    if ($position & DOMDocumentFragment::DOCUMENT_POSITION_CONTAINS) {
94        echo "結果: 'child-element' は 'sibling-element' を含んでいます。(このケースでは偽となります)\n";
95    } else {
96        echo "結果: 'child-element' は 'sibling-element' を含んでいません。(正しい結果)\n";
97    }
98    echo "\n";
99} else {
100    echo "エラー: 'child-element' または 'sibling-element' が見つかりませんでした。\n\n";
101}
102
103?>

DOMDocumentFragment::DOCUMENT_POSITION_CONTAINS定数は、PHPでHTMLやXMLドキュメントの構造を扱う際に、あるDOMノードが別のノードを内部に含んでいるかどうかを判断するために使用される整数値です。この定数は、主にDOMNode::compareDocumentPosition()メソッドの戻り値を解析する際に利用されます。compareDocumentPosition()メソッドは、比較対象の2つのノード間の相対的な位置関係を示すビットマスク（複数の情報をまとめた整数）を戻り値として返します。

サンプルコードでは、まずHTMLコンテンツをDOMDocumentオブジェクトにロードし、DOMツリーを構築しています。その後、getElementById()メソッドを使って特定のIDを持つ要素（親要素、子要素、兄弟要素など）を取得します。これらの要素間でcompareDocumentPosition()メソッドを呼び出すことで、ノード間の位置関係が取得されます。例えば、$parentElement->compareDocumentPosition($childElement)のように呼び出した場合、$parentElementが$childElementを含んでいるかどうかを判断するには、その戻り値とDOCUMENT_POSITION_CONTAINS定数をビット論理AND演算子（&）で比較します。この比較が真であれば、親要素が子要素を含んでいることを意味します。このように、この定数を利用することで、ドキュメント内のノードの親子関係や包含関係をプログラムで正確に判定することが可能になります。DOCUMENT_POSITION_CONTAINS定数自体の型はintです。

この定数は、DOMノード間の親子関係などを判定する際に利用します。DOMDocumentFragmentクラスに属しますが、主にDOMNode::compareDocumentPosition()メソッドの戻り値を解析するのに使われます。compareDocumentPosition()の戻り値はビットマスクなので、比較にはビット論理AND演算子&を必ず使用してください。DOMDocument::loadHTML()は非HTML5コンテンツに対して警告を出す場合があるため、本番環境ではエラーハンドリングやオプション指定を検討しましょう。また、getElementById()などが要素を見つけられない場合はnullを返すため、ノード操作前には必ず存在確認を行い、予期せぬエラーを防ぎ安全にコードを利用してください。

PHP: DOCUMENT_POSITION_CONTAINS を使ってノード包含を判定する


1<?php
2
3/**
4 * DOMDocumentFragment が別のノードを含んでいるかを確認し、
5 * PHP の組み込み定数 DOCUMENT_POSITION_CONTAINS の使用例を示します。
6 *
7 * この定数は、DOMNode::compareDocumentPosition() メソッドの戻り値の一部として使用され、
8 * 参照ノードが比較対象ノードを含んでいる場合に設定されるビットフラグです。
9 *
10 * @return void
11 */
12function demonstrateDocumentPositionContains(): void
13{
14    // 新しいDOMDocumentFragmentを作成します。
15    // DOMDocumentFragmentは、軽量なDOMツリーであり、一時的なノードのコンテナとして機能します。
16    $fragment = new DOMDocumentFragment();
17
18    // DOMDocumentFragment内に子要素を作成し、追加します。
19    $childElement = new DOMElement('child');
20    $fragment->appendChild($childElement);
21
22    // DOMDocumentFragmentが子要素を含んでいるかを比較します。
23    // compareDocumentPosition() は2つのノード間の相対的な位置関係をビットマスクで返します。
24    $position = $fragment->compareDocumentPosition($childElement);
25
26    echo "--- DOMDocumentFragment と子要素の位置関係の比較 ---\n";
27
28    // DOCUMENT_POSITION_CONTAINS 定数を使って、fragmentが子要素を含んでいるかを確認します。
29    // 戻り値はビットマスクなので、ビット論理積 (&) 演算子で確認します。
30    if (($position & DOCUMENT_POSITION_CONTAINS) === DOCUMENT_POSITION_CONTAINS) {
31        echo "  - DOMDocumentFragment は 'child' 要素を含んでいます。\n";
32    } else {
33        echo "  - DOMDocumentFragment は 'child' 要素を含んでいません。\n";
34        echo "    (現在の position 値: " . $position . ")\n";
35    }
36
37    echo "\n";
38
39    // DOMDocumentFragmentに追加されていない別の要素を作成します。
40    $unrelatedElement = new DOMElement('unrelated');
41
42    // fragmentがこの要素を含んでいるかを比較します。
43    $position2 = $fragment->compareDocumentPosition($unrelatedElement);
44
45    echo "--- DOMDocumentFragment と無関係な要素の位置関係の比較 ---\n";
46
47    if (($position2 & DOCUMENT_POSITION_CONTAINS) === DOCUMENT_POSITION_CONTAINS) {
48        echo "  - DOMDocumentFragment は 'unrelated' 要素を含んでいます。\n";
49    } else {
50        echo "  - DOMDocumentFragment は 'unrelated' 要素を含んでいません。\n";
51        echo "    (現在の position 値: " . $position2 . ")\n";
52    }
53}
54
55// 関数を実行して結果を出力します。
56demonstrateDocumentPositionContains();

このPHPコードは、DOM（Document Object Model）操作において、あるノードが別のノードを含んでいるかを確認するための組み込み定数DOCUMENT_POSITION_CONTAINSの使用方法を示しています。この定数はDOMDocumentFragmentクラスに属しますが、主にDOMNode::compareDocumentPosition()メソッドの戻り値の一部として利用されます。compareDocumentPosition()メソッドは、2つのノード間の相対的な位置関係を示す整数値（ビットマスク）を返します。

DOMDocumentFragmentは、実際のドキュメントに直接影響を与えずにノードを一時的に保持・操作できる軽量なDOMツリーであり、効率的なDOM操作によく使用されます。

サンプルコードでは、まずDOMDocumentFragmentを作成し、その中にDOMElementを追加しています。その後、fragmentが追加した子要素を含んでいるかをcompareDocumentPosition()メソッドで比較します。このメソッドの戻り値であるビットマスクに対し、DOCUMENT_POSITION_CONTAINS定数（int型）をビット論理積演算子&で適用することで、fragmentが子ノードを含んでいるかどうかが判定できます。この定数は、参照ノードが比較対象ノードを含んでいる場合に、比較結果のビットマスクに設定されるフラグの一つです。コードの実行結果として、「DOMDocumentFragment は 'child' 要素を含んでいます」と表示されます。

一方、fragmentに追加されていない別の要素と比較した場合、DOCUMENT_POSITION_CONTAINSのビットは立たないため、「DOMDocumentFragment は 'unrelated' 要素を含んでいません」と表示され、正しく包含関係が判定されていることを確認できます。この定数を利用することで、Webページの動的な操作などでノードの親子関係や包含関係を正確に判断し、適切な処理を行うことが可能になります。

この定数は、DOMNode::compareDocumentPosition()メソッドの戻り値（ビットマスク）と組み合わせて使用し、ノード間の位置関係を確認します。戻り値は複数の状態を示すため、単に比較するのではなく、ビット論理積（&）演算子を用いて特定のフラグが立っているかを確認する必要があります。この定数自体が直接真偽値を返すわけではない点に注意してください。DOMDocumentFragmentは、複数のノードを一時的にまとめる軽量なDOMツリーとして活用できます。定数の意味とビット演算子の使い方を正しく理解し、安全にコードを利用してください。