【PHP8.x】Dom\Attr::DOCUMENT_POSITION_CONTAINED_BY定数の使い方

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

作成日: 2025年09月11日更新日: 2025年11月16日

基本的な使い方

DOCUMENT_POSITION_CONTAINED_BY定数は、PHPのDOM拡張機能において、DOMツリー上の2つのノード間の位置関係を比較する際に利用される、特定の状態を表す定数です。この定数は、主にDom\Nodeクラスに定義されているcompareDocumentPosition()メソッドの戻り値の一つとして使用されます。

compareDocumentPosition()メソッドは、指定された2つのノードがDOMツリー内でどのような相対的な位置にあるかを示すビットマスクを返します。この戻り値に含まれるビットフラグの一つがDOCUMENT_POSITION_CONTAINED_BYです。このフラグがセットされている場合、それはメソッドの第一引数で指定されたノード（比較対象ノード）が、第二引数で指定されたノード（参照ノード）の中に論理的に含まれている状態であることを意味します。

例えば、HTMLドキュメント内で<p>要素が<div>要素の子要素として存在する場合、<p>要素を比較対象ノード、<div>要素を参照ノードとしてcompareDocumentPosition()メソッドを実行すると、戻り値にDOCUMENT_POSITION_CONTAINED_BYが含まれることになります。これは、<div>要素が<p>要素の親、または祖先要素であり、<div>が<p>を内包している関係を示唆します。

システムエンジニアを目指す方にとって、この定数はDOMツリーの走査や特定のノードの検索、あるいは要素の追加・削除などの操作において、ノード間の親子関係や内包関係をプログラム的に正確に判断するための重要な基準となります。DOM操作を行う上で、ノードの位置関係を理解し、適切に処理するために欠かせない定数の一つです。

構文(syntax)


1<?php
2echo Dom\Attr::DOCUMENT_POSITION_CONTAINED_BY;
3?>

引数(parameters)

引数なし

引数はありません

戻り値(return)

戻り値なし

戻り値はありません

サンプルコード

PHP: DOMノード位置関係比較とDOCUMENT_POSITION_PRECEDING


1<?php
2
3/**
4 * 2つのDOMノード間の位置関係を比較し、結果を表示する関数。
5 * システムエンジニアを目指す初心者が、DOMノードの位置関係を示す定数の使い方を理解できるように設計されています。
6 *
7 * PHP 8のDom拡張におけるDom\Node::compareDocumentPosition()メソッドは、
8 * 呼び出し元のノードが引数で指定されたノードに対してどのような位置関係にあるかをビットマスクで返します。
9 * この戻り値は複数の定数（例: Dom\Node::DOCUMENT_POSITION_PRECEDING, Dom\Node::DOCUMENT_POSITION_CONTAINED_BY）
10 * の組み合わせとなります。
11 *
12 * 注: リファレンス情報では「所属クラス: Dom\Attr」とありますが、
13 * これらの位置関係を示す定数は、PHP 8の新しいDOM拡張では Dom\Node クラスに定義されています。
14 * Dom\Attr クラスは Dom\Node を継承しているため、Dom\Attr インスタンスでも
15 * compareDocumentPosition() メソッドを使用できますが、
16 * 一般的な要素ノード間の位置関係を示すため、ここでは Dom\Element (Dom\Nodeの子孫) を使用します。
17 */
18function demonstrateNodePositionComparison(): void
19{
20    // 新しいDOMドキュメントを作成し、サンプルHTMLコンテンツをロードします。
21    // PHP 8のDom拡張はより厳密なXMLパーサを使用するため、HTMLは整形式である必要があります。
22    $dom = new Dom\Document();
23    $dom->loadHTML(
24        '<!DOCTYPE html>
25        <html>
26        <head><title>DOM Position Test</title></head>
27        <body>
28            <div id="container">
29                <span id="first_child">Hello</span>
30                <p id="second_child">World</p>
31            </div>
32            <div id="next_sibling">Another Element</div>
33        </body>
34        </html>'
35    );
36
37    // 比較対象となるDOMノードを取得します。
38    // getElementByIdはDom\Elementインスタンスを返します。
39    $container = $dom->getElementById('container');
40    $firstChild = $dom->getElementById('first_child');
41    $secondChild = $dom->getElementById('second_child');
42    $nextSibling = $dom->getElementById('next_sibling');
43
44    // ノードが正しく取得できたか確認
45    if (!$container || !$firstChild || !$secondChild || !$nextSibling) {
46        echo "Error: One or more required DOM elements not found. Exiting.\n";
47        return;
48    }
49
50    echo "--- DOM ノード位置関係の比較例 ---\n\n";
51
52    // 例1: 親子関係の比較
53    // 'first_child' ノードが 'container' ノードの中に含まれているか
54    echo "1. 'first_child' と 'container' の比較:\n";
55    // compareDocumentPositionは、呼び出し元のノードが引数のノードに対してどうかの関係を返します。
56    // つまり、$firstChild が $container に対してどういう位置か。
57    $position1 = $firstChild->compareDocumentPosition($container);
58    echo "  生の結果 (ビットマスク): " . $position1 . "\n";
59
60    // DOCUMENT_POSITION_CONTAINED_BY は、呼び出し元ノードが引数ノードの子孫である場合に設定されるビットです。
61    if (($position1 & Dom\Node::DOCUMENT_POSITION_CONTAINED_BY) === Dom\Node::DOCUMENT_POSITION_CONTAINED_BY) {
62        echo "  - 'first_child' は 'container' の中に含まれています (DOCUMENT_POSITION_CONTAINED_BY)。\n";
63    }
64    echo "\n";
65
66
67    // 例2: 兄弟関係の比較 (DOMツリー上での出現順序)
68    // 'second_child' ノードが 'first_child' ノードより後に出現するか
69    echo "2. 'second_child' と 'first_child' の比較:\n";
70    // $secondChild が $firstChild に対してどういう位置か。
71    $position2 = $secondChild->compareDocumentPosition($firstChild);
72    echo "  生の結果 (ビットマスク): " . $position2 . "\n";
73
74    // DOCUMENT_POSITION_PRECEDING は、呼び出し元ノードが引数ノードより前に出現する場合に設定されるビットです。
75    // ここでは $secondChild は $firstChild の後に出現するため、このビットは設定されません。
76    if (($position2 & Dom\Node::DOCUMENT_POSITION_PRECEDING) === Dom\Node::DOCUMENT_POSITION_PRECEDING) {
77        echo "  - 'second_child' は 'first_child' より前に出現しています (DOCUMENT_POSITION_PRECEDING)。\n";
78    } else {
79        echo "  - 'second_child' は 'first_child' より後に出現しています。\n";
80    }
81    echo "\n";
82
83
84    // 例3: 異なる親を持つノード間の比較 (DOMツリー上での出現順序)
85    // 'next_sibling' ノードが 'container' ノードより後に出現するか
86    echo "3. 'next_sibling' と 'container' の比較:\n";
87    // $nextSibling が $container に対してどういう位置か。
88    $position3 = $nextSibling->compareDocumentPosition($container);
89    echo "  生の結果 (ビットマスク): " . $position3 . "\n";
90
91    if (($position3 & Dom\Node::DOCUMENT_POSITION_PRECEDING) === Dom\Node::DOCUMENT_POSITION_PRECEDING) {
92        echo "  - 'next_sibling' は 'container' より前に出現しています (DOCUMENT_POSITION_PRECEDING)。\n";
93    } else {
94        echo "  - 'next_sibling' は 'container' より後に出現しています。\n";
95    }
96    echo "\n";
97}
98
99// 関数を実行して、DOMノードの位置関係の比較結果を表示します。
100demonstrateNodePositionComparison();

このサンプルコードは、PHP 8のDOM拡張機能を利用し、ウェブページの構造を表すDOM（Document Object Model）ノード間の位置関係を比較する方法をシステムエンジニアを目指す初心者向けに示しています。ここでは、Dom\NodeクラスのcompareDocumentPosition()メソッドを中心に解説しています。

compareDocumentPosition()メソッドは、呼び出し元のノードが引数で指定されたノードに対してどのような位置関係にあるかを、整数値のビットマスクとして返します。この戻り値は単一の値ではなく、複数の位置関係を示す定数を組み合わせたものです。

例えば、リファレンス情報で言及されているDom\Attr::DOCUMENT_POSITION_CONTAINED_BY定数は、PHP 8のDOM拡張ではDom\Node::DOCUMENT_POSITION_CONTAINED_BYとして定義されており、呼び出し元のノードが引数ノードの子孫、つまりその中に含まれている場合に、戻り値のビットマスクに含まれます。同様に、キーワードにあるDom\Node::DOCUMENT_POSITION_PRECEDING定数は、呼び出し元のノードが引数ノードより先にDOMツリーで出現する場合に設定されるビットです。

サンプルコードでは、container、first_child、second_child、next_siblingといった異なるノードを取得し、それぞれのペアでcompareDocumentPosition()メソッドを実行しています。そして、戻り値のビットマスクに対してビット演算子&を用いて、DOCUMENT_POSITION_CONTAINED_BYやDOCUMENT_POSITION_PRECEDINGといった定数と一致するかどうかを判定することで、ノード間の親子関係や出現順序を具体的に判断する手順を詳しく紹介しています。これにより、DOMノードが互いに対してどのような相対位置にあるかを正確に把握する方法を学ぶことができます。

このサンプルコードでは、DOMノードの位置関係を比較するDom\Node::compareDocumentPosition()メソッドと、その結果を示す定数の使い方を学習します。まず、リファレンス情報では定数がDom\Attrクラスに属するとありますが、PHP 8のDOM拡張ではDom\Nodeクラスで定義されており、一般的にはDom\ElementなどのDom\Nodeの子孫クラスで利用します。このメソッドは、呼び出し元のノードが引数のノードに対してどういう位置関係にあるかをビットマスクで返しますので、複数の定数をビット論理積&で組み合わせて判定する必要があります。特にDOCUMENT_POSITION_PRECEDINGは、呼び出し元ノードが引数ノードよりもDOMツリー上で先に出現する場合に設定されるビットです。また、loadHTMLで読み込むHTMLは整形式である必要があり、getElementByIdで取得したノードがnullでないか必ず確認してから利用してください。

PHP DOMノード関係: DOCUMENT_POSITION_CONTAINED_BYを理解する


1<?php
2
3/**
4 * DOMノード間の位置関係を比較し、DOM_DOCUMENT_POSITION_CONTAINED_BY 定数の意味を示すサンプルコードです。
5 *
6 * DOM_DOCUMENT_POSITION_CONTAINED_BY 定数は、Dom\Node::compareDocumentPosition() メソッドの戻り値の一部として使用され、
7 * 比較対象のノードが、このノード (メソッドを呼び出したノード) の内部に含まれていることを示します。
8 * (例: $nodeA->compareDocumentPosition($nodeB) で、結果に DOM_DOCUMENT_POSITION_CONTAINED_BY が含まれる場合、
9 * $nodeB が $nodeA に含まれていることを意味します。)
10 */
11function demonstrateDocumentPositionContainedBy(): void
12{
13    // 1. 新しいDOMドキュメントを作成し、HTMLコンテンツを読み込みます。
14    $dom = new DOMDocument();
15    // 適切なHTMLを読み込むことで、親と子のノード関係を明確にします。
16    // loadHTML はボディタグなどを自動で補完するため、シンプルなHTMLでも機能します。
17    $dom->loadHTML('
18        <div id="parent-element">
19            <span id="child-element">Hello PHP!</span>
20        </div>
21    ');
22
23    // 2. 比較対象となるDOMノードを取得します。
24    // XPathは、特定の要素をIDなどで確実に取得するのに便利です。
25    $xpath = new DOMXPath($dom);
26    $parentElement = $xpath->query('//div[@id="parent-element"]')->item(0);
27    $childElement = $xpath->query('//span[@id="child-element"]')->item(0);
28
29    // ノードが正しく取得できたか確認します。
30    if (!$parentElement || !$childElement) {
31        echo "エラー: 必要なDOMノードが見つかりませんでした。\n";
32        return;
33    }
34
35    echo "--- DOM ノードの位置関係の比較 ---\n\n";
36
37    // 3. 親ノード ($parentElement) と子ノード ($childElement) の位置関係を比較します。
38    // この比較では、$childElement が $parentElement の内部に含まれているため、
39    // 結果には \Dom\Node::DOCUMENT_POSITION_CONTAINED_BY が含まれるはずです。
40    // また、$parentElement は $childElement を含んでいるため、
41    // 結果には \Dom\Node::DOCUMENT_POSITION_CONTAINS も含まれます。
42    //
43    // compareDocumentPosition() の戻り値はビットマスクであるため、
44    // 論理AND演算子 (&) を使用して特定の定数が含まれているかを確認します。
45    $position = $parentElement->compareDocumentPosition($childElement);
46
47    echo "① '$parentElement->nodeName' と '$childElement->nodeName' を比較:\n";
48    echo "   \$parentElement->compareDocumentPosition(\$childElement) の結果: " . $position . " (ビットマスク)\n";
49
50    // DOM_DOCUMENT_POSITION_CONTAINED_BY が結果に含まれるかチェック
51    if ($position & \Dom\Node::DOCUMENT_POSITION_CONTAINED_BY) {
52        echo "   - \Dom\Node::DOCUMENT_POSITION_CONTAINED_BY が含まれています。\n";
53        echo "     これは「\$childElement は \$parentElement の内部に含まれている」ことを意味します。\n";
54    } else {
55        echo "   - \Dom\Node::DOCUMENT_POSITION_CONTAINED_BY は含まれていません。\n";
56    }
57
58    // DOM_DOCUMENT_POSITION_CONTAINS が結果に含まれるかチェック
59    if ($position & \Dom\Node::DOCUMENT_POSITION_CONTAINS) {
60        echo "   - \Dom\Node::DOCUMENT_POSITION_CONTAINS が含まれています。\n";
61        echo "     これは「\$parentElement は \$childElement を含んでいる」ことを意味します。\n";
62    } else {
63        echo "   - \Dom\Node::DOCUMENT_POSITION_CONTAINS は含まれていません。\n";
64    }
65
66    echo "\n";
67
68    // 4. 逆の順序でノードの位置関係を比較します。
69    // 子ノード ($childElement) と親ノード ($parentElement) を比較します。
70    // この場合、$parentElement は $childElement に含まれていないため、
71    // 結果には \Dom\Node::DOCUMENT_POSITION_CONTAINED_BY は含まれません。
72    // しかし、$childElement の親であるため、結果には \Dom\Node::DOCUMENT_POSITION_PRECEDING が含まれます。
73    $positionReversed = $childElement->compareDocumentPosition($parentElement);
74
75    echo "② '$childElement->nodeName' と '$parentElement->nodeName' を比較:\n";
76    echo "   \$childElement->compareDocumentPosition(\$parentElement) の結果: " . $positionReversed . " (ビットマスク)\n";
77
78    if ($positionReversed & \Dom\Node::DOCUMENT_POSITION_CONTAINED_BY) {
79        echo "   - \Dom\Node::DOCUMENT_POSITION_CONTAINED_BY が含まれています。\n";
80        echo "     これは「\$parentElement は \$childElement の内部に含まれている」ことを意味します（この例では発生しません）。\n";
81    } else {
82        echo "   - \Dom\Node::DOCUMENT_POSITION_CONTAINED_BY は含まれていません。\n";
83        echo "     これは「\$parentElement は \$childElement の内部に含まれていない」ことを意味します。\n";
84    }
85
86    // 他の関連する定数も確認することで、理解を深めます。
87    if ($positionReversed & \Dom\Node::DOCUMENT_POSITION_PRECEDING) {
88        echo "   - \Dom\Node::DOCUMENT_POSITION_PRECEDING が含まれています。\n";
89        echo "     これは「\$parentElement が \$childElement の前に位置している」ことを意味します。\n";
90    }
91}
92
93// 関数の実行
94demonstrateDocumentPositionContainedBy();

PHPの\Dom\Node::DOCUMENT_POSITION_CONTAINED_BY定数は、HTMLやXML文書の構造を扱うDOMノード間で、その位置関係を比較する際に用いられる特別な値の一つです。この定数自体に引数や戻り値はありませんが、主に\Dom\Node::compareDocumentPosition()メソッドの戻り値の一部として利用されます。

compareDocumentPosition()メソッドは、二つのDOMノードが文書内でどのような相対的な位置にあるかを示すビットマスク形式の整数値を返します。この戻り値にDOCUMENT_POSITION_CONTAINED_BY定数が含まれている場合、それは比較対象のノードが、メソッドを呼び出したノードの内部（子孫要素）に含まれていることを意味します。

例えば、$parentElement->compareDocumentPosition($childElement)のように比較し、その結果にDOCUMENT_POSITION_CONTAINED_BYが含まれていれば、「$childElementは$parentElementの内部に存在する」という関係性が成り立っていると判断できます。サンプルコードでは、親のdiv要素と子のspan要素を用いてこの挙動を検証しています。親要素から子要素を比較すると、spanがdivに含まれているため、DOCUMENT_POSITION_CONTAINED_BYが検出されます。一方、子要素から親要素を比較した場合は、親要素が子要素に含まれることはないため、この定数は検出されません。compareDocumentPosition()の戻り値は複数の位置情報を同時に示すビットマスクであるため、特定の定数が含まれているかを確認するには論理AND演算子（&）を使用します。

PHPのDOCUMENT_POSITION_CONTAINED_BY定数は、Dom\NodeクラスのcompareDocumentPosition()メソッドが返す、二つのDOMノード間の位置関係を示すビットマスクの一部です。このメソッドの戻り値は複数の状態を同時に表すため、特定の定数が含まれているかを確認するには、論理AND演算子（&）を用いて比較する必要があります。単に数値が一致するかどうかで判断すると、期待する結果が得られない可能性がありますのでご注意ください。

DOCUMENT_POSITION_CONTAINED_BYは、引数で渡されたノードが、メソッドを呼び出したノードの内部に含まれている状態を示します。これに対し、DOCUMENT_POSITION_CONTAINSは、メソッドを呼び出したノードが引数のノードを含んでいる状態を示すため、両者の意味を混同しないように正確に理解することが重要です。また、DOM操作で要素を取得する際は、サンプルコードのように、対象のノードが正しく取得できたかを必ず確認してから処理を進めるようにしてください。存在しないノードに対して操作を行うとエラーが発生します。