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

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

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

基本的な使い方

DOCUMENT_POSITION_CONTAINED_BY定数は、DOMノード間の位置関係において、メソッドを呼び出したノードが、比較対象のノードに包含されている状態を表す定数です。この定数は、文書内の要素の階層的な関係、特に包含関係をプログラムで識別するために利用されます。

主にPHPのDOM拡張におけるDom\Nodeクラスが提供するcompareDocumentPosition()メソッドの戻り値として使用されます。compareDocumentPosition()メソッドは、二つのノードが文書内でどのような相対的な位置にあるかを比較し、その結果をビットマスク値として返します。Dom\CommentクラスのようなDOMノードを扱う際に、他のノードとの相対的な位置関係を判断するために用いられます。

もしcompareDocumentPosition()メソッドの実行結果にこのDOCUMENT_POSITION_CONTAINED_BY定数が含まれていた場合、それは「メソッドを呼び出したノードが、比較対象のノードの内側に位置している（つまり、呼び出し元のノードが比較対象ノードの子孫であるか、またはそのテキストノードなど一部である）」という状態を示します。例えば、ある<p>要素がその親である<div>要素と比較された際に、<p>側から見れば<div>に包含されていると判断されます。

この定数はビットマスクの一部であり、他の位置関係を示す定数（例えば、DOCUMENT_POSITION_CONTAINSなど）と組み合わせて使用されることで、より複雑なノード間の位置関係を詳細に表現することが可能です。システムエンジニアがHTMLやXMLのような階層構造を持つ文書をPHPで処理する際に、特定の要素が別の要素の内部にあるかどうかを正確に判定する上で非常に重要な役割を果たします。

構文(syntax)


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

引数(parameters)

引数なし

引数はありません

戻り値(return)

戻り値なし

戻り値はありません

サンプルコード

PHP DOMノード位置比較で先頭を判定する


1<?php
2
3// PHP 8以降では、DOM拡張のクラスはDom名前空間にあります。
4use Dom\Document;
5use Dom\Node;
6use Dom\Element;
7
8/**
9 * 2つのDOMノードの相対的な位置関係を比較し、結果を表示します。
10 *
11 * この関数は、HTMLドキュメントを作成し、そこから特定のノードを取得します。
12 * その後、Node::compareDocumentPosition() メソッドを使用して、
13 * 異なるノード間の位置関係（先行、後続、包含、被包含など）を判断し、
14 * システムエンジニアを目指す初心者にも分かりやすく出力します。
15 */
16function demonstrateNodePositionComparison(): void
17{
18    // 1. シンプルなHTMLドキュメントを読み込む
19    $html = <<<HTML
20<!DOCTYPE html>
21<html>
22<body>
23    <div id="container">
24        <p id="first-p">最初の段落です。</p>
25        <span id="target-span">ターゲットのスパンです。</span>
26        <p id="last-p">最後の段落です。</p>
27    </div>
28</body>
29</html>
30HTML;
31
32    $doc = new Document();
33    $doc->loadHTML($html);
34
35    // 2. 比較対象となるノードを取得
36    // getElementById は Dom\Document のメソッドです。
37    $container = $doc->getElementById('container');
38    $firstParagraph = $doc->getElementById('first-p');
39    $targetSpan = $doc->getElementById('target-span');
40    $lastParagraph = $doc->getElementById('last-p');
41
42    // ノードが取得できなかった場合のチェック
43    if (!$container || !$firstParagraph || !$targetSpan || !$lastParagraph) {
44        echo "エラー: 必要なノードがすべて取得できませんでした。\n";
45        return;
46    }
47
48    // 3. 異なるノードペアで比較を実行し、結果を出力
49    echo "--- 比較例: ノード 'first-p' と 'target-span' ---\n";
50    // 'first-p' は 'target-span' より前にあります
51    compareAndExplain($firstParagraph, $targetSpan);
52
53    echo "\n--- 比較例: ノード 'target-span' と 'first-p' ---\n";
54    // 'target-span' は 'first-p' より後にあります
55    compareAndExplain($targetSpan, $firstParagraph);
56
57    echo "\n--- 比較例: ノード 'container' と 'target-span' ---\n";
58    // 'container' は 'target-span' を含んでいます
59    compareAndExplain($container, $targetSpan);
60
61    echo "\n--- 比較例: ノード 'target-span' と 'container' ---\n";
62    // 'target-span' は 'container' に含まれています
63    compareAndExplain($targetSpan, $container);
64
65    echo "\n--- 比較例: ノード 'first-p' と 'last-p' ---\n";
66    // 'first-p' は 'last-p' より前にあります
67    compareAndExplain($firstParagraph, $lastParagraph);
68}
69
70/**
71 * 2つのDOMノードの相対的な位置を比較し、結果を分かりやすく表示します。
72 *
73 * @param Node $nodeA 比較の基準となるノード。
74 * @param Node $nodeB 比較対象のノード。
75 */
76function compareAndExplain(Node $nodeA, Node $nodeB): void
77{
78    // Node::compareDocumentPosition() は、ノードBから見てノードAの位置を示す
79    // ビットマスク（複数の状態を同時に表す数値）を返します。
80    // これらの定数は Dom\Node クラスに定義されており、Dom\Commentのような
81    // 他のDomノードクラスも継承して使用できます。
82    $position = $nodeA->compareDocumentPosition($nodeB);
83
84    $nodeA_id = ($nodeA instanceof Element ? $nodeA->id : '不明なノード');
85    $nodeB_id = ($nodeB instanceof Element ? $nodeB->id : '不明なノード');
86
87    echo "ノード A ('{$nodeA_id}') と ノード B ('{$nodeB_id}') の関係:\n";
88
89    // DOCUMENT_POSITION_PRECEDING:
90    // ノードBがノードAよりも前に位置する場合、このビットが設定されます。
91    // (つまり、ノードAから見ると、ノードBは先行している)
92    if (($position & Node::DOCUMENT_POSITION_PRECEDING) === Node::DOCUMENT_POSITION_PRECEDING) {
93        echo "  - ノード B ('{$nodeB_id}') はノード A ('{$nodeA_id}') に先行しています。\n";
94    }
95
96    // DOCUMENT_POSITION_FOLLOWING:
97    // ノードBがノードAよりも後に位置する場合、このビットが設定されます。
98    // (つまり、ノードAから見ると、ノードBは後続している)
99    if (($position & Node::DOCUMENT_POSITION_FOLLOWING) === Node::DOCUMENT_POSITION_FOLLOWING) {
100        echo "  - ノード B ('{$nodeB_id}') はノード A ('{$nodeA_id}') の後に続いています。\n";
101    }
102
103    // DOCUMENT_POSITION_CONTAINS:
104    // ノードAがノードBを含んでいる（ノードBがノードAの子孫である）場合、このビットが設定されます。
105    if (($position & Node::DOCUMENT_POSITION_CONTAINS) === Node::DOCUMENT_POSITION_CONTAINS) {
106        echo "  - ノード A ('{$nodeA_id}') はノード B ('{$nodeB_id}') を含んでいます。\n";
107    }
108
109    // DOCUMENT_POSITION_CONTAINED_BY:
110    // ノードAがノードBに含まれている（ノードAがノードBの子孫である）場合、このビットが設定されます。
111    // これはリファレンス情報で言及された定数の一つです。
112    if (($position & Node::DOCUMENT_POSITION_CONTAINED_BY) === Node::DOCUMENT_POSITION_CONTAINED_BY) {
113        echo "  - ノード A ('{$nodeA_id}') はノード B ('{$nodeB_id}') に含まれています。\n";
114    }
115
116    // DOCUMENT_POSITION_DISCONNECTED:
117    // 2つのノードが同じドキュメントツリーに属していない場合、このビットが設定されます。
118    if (($position & Node::DOCUMENT_POSITION_DISCONNECTED) === Node::DOCUMENT_POSITION_DISCONNECTED) {
119        echo "  - ノード A とノード B は同じドキュメントツリー内にありません。\n";
120    }
121
122    // 0 の場合、通常は同じノードを比較したとき、または特別な関係がないとき。
123    if ($position === 0) {
124        echo "  - ノード A とノード B は同じノードであるか、特別な位置関係がありません。\n";
125    }
126}
127
128// サンプルコードの実行
129demonstrateNodePositionComparison();

このPHPコードは、ウェブページの構成要素（DOMノード）の相対的な位置関係を調べる方法を、システムエンジニアを目指す初心者向けに示しています。中心となるのはDom\NodeクラスのcompareDocumentPosition()メソッドです。このメソッドは、比較の基準となるノードと、比較対象のノードという2つの引数を受け取ります。戻り値として、基準ノードから見た対象ノードの位置を示す「ビットマスク」と呼ばれる整数を返します。このビットマスクは、複数の状態を同時に表現する特別な数値です。

例えば、リファレンス情報で示されているDom\Node::DOCUMENT_POSITION_CONTAINED_BY定数は、基準ノードが比較対象ノードに含まれている（つまり、基準ノードが対象ノードの子孫である）場合に、戻り値のビットマスクの一部として含まれます。また、キーワードとして挙げられたDom\Node::DOCUMENT_POSITION_PRECEDING定数は、比較対象ノードが基準ノードよりも前に位置する場合にビットマスクに含まれます。

サンプルコードでは、まずHTMLドキュメントを読み込み、そこから特定のノードをいくつか取得しています。次に、これらのノードペアに対してcompareDocumentPosition()メソッドを適用し、その結果のビットマスクをこれらの定数と比較することで、それぞれのノードが互いに対して「先行しているか」「含まれているか」といった具体的な位置関係を判別しています。そして、その結果を初心者にも理解しやすいように説明文として出力しています。これにより、DOMツリー内での要素の位置関係をプログラムで詳細に把握し、複雑なウェブページの操作に応用する基礎を学ぶことができます。

このサンプルコードは、DOMノードの位置関係を比較する compareDocumentPosition() メソッドの利用法を示しています。このメソッドは複数の状態を同時に示す「ビットマスク」という特殊な数値を返すため、個々の位置関係を判定するにはビットAND演算子 (&) を用いる点に注意が必要です。リファレンスに記載の Dom\Comment::DOCUMENT_POSITION_CONTAINED_BY のような定数は、基底クラスである Dom\Node で定義されており、様々なDOMノードで共通に利用されます。PHP 8以降ではDOM拡張クラスが Dom 名前空間になったため、use Dom\... の記述が必須です。また、getElementById などでノードが取得できない場合は null が返されるため、必ず取得結果をチェックし、予期せぬエラーを防ぐようにしてください。

PHP DOM Document Position ContainedBy 判定


1<?php
2
3/**
4 * PHP 8 の Dom 拡張における Dom\Comment::DOCUMENT_POSITION_CONTAINED_BY 定数の使用例を示します。
5 *
6 * DOCUMENT_POSITION_CONTAINED_BY 定数は、Dom\Node::compareDocumentPosition() メソッドの
7 * 戻り値のビットマスクの一部として使用されます。
8 * この定数は、比較対象のノードが呼び出し元のノードに含まれている（子孫である）場合に設定されます。
9 * Dom\Comment クラスは Dom\Node を継承しているため、その定数とメソッドを利用できます。
10 */
11function demonstrateDocumentPositionContainedBy(): void
12{
13    // Dom\Document を作成し、サンプルHTMLを読み込む
14    $dom = new Dom\Document();
15    // HTMLの内容は Dom\Node の階層関係を明確にするために使用されます。
16    $dom->loadHtml('
17        <html>
18            <body>
19                <div id="parent_element">
20                    <p id="child_paragraph">これは段落です。</p>
21                    <!-- これはコメントノードです -->
22                    <span id="child_span">これはスパンです。</span>
23                </div>
24            </body>
25        </html>
26    ');
27
28    // 比較に使用するノードを取得する
29    $parentElement = $dom->getElementById('parent_element');
30    $paragraphNode = $dom->getElementById('child_paragraph');
31    $spanNode = $dom->getElementById('child_span');
32
33    // コメントノードを見つける
34    // getElementById などでは取得できないため、親ノードの子ノードを走査して見つけます。
35    $commentNode = null;
36    if ($parentElement) {
37        foreach ($parentElement->childNodes as $node) {
38            if ($node instanceof Dom\Comment) {
39                $commentNode = $node;
40                break;
41            }
42        }
43    }
44
45    // 必要なノードが全て取得できたか確認
46    if (!$parentElement || !$paragraphNode || !$spanNode || !$commentNode) {
47        echo "エラー: 必要なDOMノードが見つかりませんでした。\n";
48        return;
49    }
50
51    echo "--- Dom\Node::compareDocumentPosition() と DOCUMENT_POSITION_CONTAINED_BY の例 ---\n\n";
52
53    // 例1: 子ノードが親ノードに含まれているかを確認する
54    // paragraphNode が parentElement に含まれているかを判定します。
55    // compareDocumentPosition の呼び出し元が $paragraphNode, 引数が $parentElement です。
56    // 結果のビットマスクに DOCUMENT_POSITION_CONTAINED_BY が含まれるはずです。
57    $positionResult1 = $paragraphNode->compareDocumentPosition($parentElement);
58    $isParagraphContainedByParent = ($positionResult1 & Dom\Comment::DOCUMENT_POSITION_CONTAINED_BY);
59
60    echo "ノード 'p#child_paragraph' は 'div#parent_element' に含まれていますか？\n";
61    if ($isParagraphContainedByParent) {
62        echo "  -> はい、含まれています (DOCUMENT_POSITION_CONTAINED_BY が検出されました)。\n";
63    } else {
64        echo "  -> いいえ、含まれていません。\n";
65    }
66    echo "\n";
67
68    // 例2: コメントノードが親ノードに含まれているかを確認する
69    // commentNode が parentElement に含まれているかを判定します。
70    // 結果のビットマスクに DOCUMENT_POSITION_CONTAINED_BY が含まれるはずです。
71    $positionResult2 = $commentNode->compareDocumentPosition($parentElement);
72    $isCommentContainedByParent = ($positionResult2 & Dom\Comment::DOCUMENT_POSITION_CONTAINED_BY);
73
74    echo "コメントノードは 'div#parent_element' に含まれていますか？\n";
75    if ($isCommentContainedByParent) {
76        echo "  -> はい、含まれています (DOCUMENT_POSITION_CONTAINED_BY が検出されました)。\n";
77    } else {
78        echo "  -> いいえ、含まれていません。\n";
79    }
80    echo "\n";
81
82    // 例3: 兄弟ノード間で含まれる関係があるかを確認する
83    // paragraphNode が spanNode に含まれているかを判定します。
84    // 兄弟ノードなので、含まれる関係はありません (DOCUMENT_POSITION_CONTAINED_BY は検出されません)。
85    // 代わりに、位置関係 (PRECEDING や FOLLOWING) が検出されるはずです。
86    $positionResult3 = $paragraphNode->compareDocumentPosition($spanNode);
87    $isParagraphContainedBySpan = ($positionResult3 & Dom\Comment::DOCUMENT_POSITION_CONTAINED_BY);
88
89    echo "ノード 'p#child_paragraph' は 'span#child_span' に含まれていますか？\n";
90    if ($isParagraphContainedBySpan) {
91        echo "  -> はい、含まれています (DOCUMENT_POSITION_CONTAINED_BY が検出されました)。\n";
92    } else {
93        echo "  -> いいえ、含まれていません。\n";
94        if ($positionResult3 & Dom\Node::DOCUMENT_POSITION_FOLLOWING) {
95            echo "  (実際には、'p#child_paragraph' は 'span#child_span' の前に位置しています)。\n";
96        } elseif ($positionResult3 & Dom\Node::DOCUMENT_POSITION_PRECEDING) {
97            echo "  (実際には、'p#child_paragraph' は 'span#child_span' の後に位置しています)。\n";
98        }
99    }
100}
101
102// 関数を実行
103demonstrateDocumentPositionContainedBy();

Dom\Comment::DOCUMENT_POSITION_CONTAINED_BYは、PHPのDOMツリーにおけるノード間の親子関係を判定するための定数です。この定数はDom\Node::compareDocumentPosition()メソッドの戻り値（ビットマスク）として利用されます。Dom\CommentクラスはDom\Nodeを継承しているため、本定数を使用できます。

compareDocumentPosition()メソッドは、呼び出し元のノードが比較対象のノードに対しどのような関係にあるかを示すビットマスクを返します。DOCUMENT_POSITION_CONTAINED_BYは、呼び出し元のノードが比較対象のノードに「含まれている」（すなわち子孫ノードである）場合に、その戻り値のビットマスクに設定されます。

サンプルコードでは、HTMLドキュメントから親要素、子要素、コメントノードを取得し、compareDocumentPosition()メソッドでノード間の位置を比較しています。例えば、$childNode->compareDocumentPosition($parentNode)の結果をこの定数とビット演算子&で比較することで、子ノードが親ノードの子孫であるかを確認しています。これにより、DOM要素の階層関係をプログラムで正確に判定することが可能です。

PHPのDom\Comment::DOCUMENT_POSITION_CONTAINED_BYは、Dom\Node::compareDocumentPosition()メソッドでノード間の位置関係を判定する定数です。この定数は、呼び出し元のノードが引数のノードの「子孫」（内部に含まれている）場合に検出されます。ノード間の包含関係を誤解しないよう特に注意してください。コメントノードはgetElementById()では取得できないため、親ノードのchildNodesをinstanceof Dom\Commentで確認して取得する必要があります。compareDocumentPosition()の戻り値はビットマスクなので、特定の状態を判定するには必ず&演算子を使用してください。