【PHP8.x】Dom\DocumentType::DOCUMENT_POSITION_CONTAINS定数の使い方

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

作成日: 2025年09月11日更新日: 2025年12月02日

基本的な使い方

『DOCUMENT_POSITION_CONTAINS定数は、2つのDOMノード間の位置関係を判定する際に、一方のノードがもう一方のノードを含んでいる状態を表す定数です。この定数は主に、DOMNode::compareDocumentPosition() メソッドの返り値に含まれるビットマスク値として使用されます。このメソッドは、2つのノードの相対的な位置関係を、複数の状態を表すフラグが組み合わさった一つの数値で返します。返された数値に DOCUMENT_POSITION_CONTAINS 定数が示すビットが含まれているかを確認することで、ノードの包含関係を判定できます。具体的には、$nodeA->compareDocumentPosition($nodeB) を実行した結果とこの定数をビット単位の論理積（&）で評価します。結果が0でなければ、$nodeA が $nodeB を子孫ノードとして含んでいる（$nodeB は $nodeA の中にある）ことを意味します。この仕組みにより、DOMツリー内における要素の親子や祖先関係を正確に把握し、複雑なドキュメント構造をプログラムから効率的に操作することが可能になります。』

構文(syntax)


1<?php
2
3$doc = new DOMDocument();
4$doc->loadXML('<root><child/></root>');
5
6$rootNode = $doc->documentElement;
7$childNode = $rootNode->firstChild;
8
9// $rootNode が $childNode を含んでいるかを判定します。
10// compareDocumentPosition() の返り値とビット論理積(&)で評価します。
11$result = $rootNode->compareDocumentPosition($childNode);
12
13if ($result & Dom\DocumentType::DOCUMENT_POSITION_CONTAINS) {
14    // この条件式は true となります。
15}
16

引数(parameters)

引数なし

引数はありません

戻り値(return)

int

Dom\DocumentType::DOCUMENT_POSITION_CONTAINS は、あるノードが別のノードを完全に含んでいることを示す整数定数です。

サンプルコード

PHP DOMノード比較 DOCUMENT_POSITION_CONTAINS を使う


1<?php
2
3/**
4 * DOMNode::compareDocumentPosition メソッドと
5 * DOMNode::DOCUMENT_POSITION_CONTAINS 定数の使い方をデモンストレーションします。
6 *
7 * この定数は、呼び出し元のノードが引数で指定されたノードを包含している場合に、
8 * compareDocumentPosition メソッドの戻り値に含まれるビットフラグです。
9 */
10function demonstrateDomNodeComparisonForBeginners(): void
11{
12    // 1. DOMDocument オブジェクトを作成し、簡単なHTMLコンテンツをロードします。
13    //    ここでは、親(body, div)と子(p)の関係を持つノードを準備します。
14    $dom = new DOMDocument();
15    $dom->loadHTML('<body><div id="container"><p id="element"></p></div></body>');
16
17    // 2. 比較対象となるノードをIDやタグ名で取得します。
18    $bodyNode = $dom->getElementsByTagName('body')->item(0);
19    $containerNode = $dom->getElementById('container');
20    $elementNode = $dom->getElementById('element');
21
22    // ノードが正しく取得できたか確認します。
23    if (!$bodyNode || !$containerNode || !$elementNode) {
24        echo "必要なDOMノードの取得に失敗しました。コードを確認してください。\n";
25        return;
26    }
27
28    echo "--- DOMNode::DOCUMENT_POSITION_CONTAINS のデモンストレーション ---\n";
29    echo "この定数は、呼び出し元のノードが引数で指定されたノードを「包含している」ことを示します。\n\n";
30
31    // DOMNode::DOCUMENT_POSITION_CONTAINS 定数の値を確認します (通常は 8)。
32    $containsConstant = DOMNode::DOCUMENT_POSITION_CONTAINS;
33    echo "  DOMNode::DOCUMENT_POSITION_CONTAINS の値: " . $containsConstant . "\n";
34    echo "  DOMNode::DOCUMENT_POSITION_CONTAINED_BY の値: " . DOMNode::DOCUMENT_POSITION_CONTAINED_BY . "\n\n";
35
36    // シナリオ1: 親ノードが子ノードを包含しているか確認
37    // $containerNode は $elementNode を包含しています。
38    echo "シナリオ1: \$containerNode (親ノード) が \$elementNode (子ノード) を包含しているか？\n";
39    $position1 = $containerNode->compareDocumentPosition($elementNode);
40    echo "  比較結果のビットマスク (\$containerNode->compareDocumentPosition(\$elementNode)): " . $position1 . "\n";
41    // ビット演算子 '&' を使用して、戻り値に DOCUMENT_POSITION_CONTAINS のビットが立っているかチェックします。
42    if (($position1 & $containsConstant) === $containsConstant) {
43        echo "  -> TRUE: \$containerNode が \$elementNode を正しく包含しています。\n";
44    } else {
45        echo "  -> FALSE: \$containerNode は \$elementNode を包含していません。\n";
46    }
47    echo "\n";
48
49    // シナリオ2: 祖先ノードが子孫ノードを包含しているか確認
50    // $bodyNode は $containerNode を包含しています。
51    echo "シナリオ2: \$bodyNode (祖先ノード) が \$containerNode (子孫ノード) を包含しているか？\n";
52    $position2 = $bodyNode->compareDocumentPosition($containerNode);
53    echo "  比較結果のビットマスク (\$bodyNode->compareDocumentPosition(\$containerNode)): " . $position2 . "\n";
54    if (($position2 & $containsConstant) === $containsConstant) {
55        echo "  -> TRUE: \$bodyNode が \$containerNode を正しく包含しています。\n";
56    } else {
57        echo "  -> FALSE: \$bodyNode は \$containerNode を包含していません。\n";
58    }
59    echo "\n";
60
61    // シナリオ3: 子ノードが親ノードを包含しているか (これは通常 false になるべき)
62    // $elementNode は $containerNode を包含していません。
63    echo "シナリオ3: \$elementNode (子ノード) が \$containerNode (親ノード) を包含しているか？\n";
64    $position3 = $elementNode->compareDocumentPosition($containerNode);
65    echo "  比較結果のビットマスク (\$elementNode->compareDocumentPosition(\$containerNode)): " . $position3 . "\n";
66    if (($position3 & $containsConstant) === $containsConstant) {
67        echo "  -> TRUE: \$elementNode が \$containerNode を包含している (予期せぬ結果)。\n";
68    } else {
69        echo "  -> FALSE: \$elementNode は \$containerNode を包含していません (正しい結果)。\n";
70    }
71    // この場合、DOCUMENT_POSITION_CONTAINED_BY (16) のビットが立つはずです。
72    // これは、「引数ノード (\$containerNode) が呼び出し元ノード (\$elementNode) を包含している」ことを意味します。
73    if (($position3 & DOMNode::DOCUMENT_POSITION_CONTAINED_BY) === DOMNode::DOCUMENT_POSITION_CONTAINED_BY) {
74        echo "  (補足: \$containerNode が \$elementNode を包含しているため、DOCUMENT_POSITION_CONTAINED_BY が立っています。)\n";
75    }
76    echo "\n";
77}
78
79// 関数を実行してデモンストレーションを開始します。
80demonstrateDomNodeComparisonForBeginners();
81

PHP 8で提供されるDOMNode::DOCUMENT_POSITION_CONTAINSは、DOM（Document Object Model）内のノード間の関係性を判別するために使用される整数定数です。この定数は、主にDOMNodeクラスのcompareDocumentPositionメソッドと組み合わせて利用されます。compareDocumentPositionメソッドは、二つのDOMノード間の相対的な位置関係をビットマスクとして整数値で返します。

DOMNode::DOCUMENT_POSITION_CONTAINSは、このビットマスクに含まれる可能性のあるフラグの一つであり、「メソッドの呼び出し元となるノードが、引数で指定されたノードをその内部に含んでいる（包含している）」状態を示します。たとえば、HTMLの<body>タグが<p>タグを囲んでいる場合、<body>ノードがcompareDocumentPositionを呼び出し、引数に<p>ノードを渡すと、返されるビットマスクにはDOMNode::DOCUMENT_POSITION_CONTAINSのビットが含まれます。

サンプルコードでは、DOMDocumentオブジェクトで作成したHTML構造から取得した親ノードと子ノードを比較し、compareDocumentPositionの戻り値とDOMNode::DOCUMENT_POSITION_CONTAINS定数をビット演算子&で比較することで、包含関係を正確に判定する方法をデモンストレーションしています。この定数は、Webページのツリー構造をプログラムで解析し、ノード間の親子や包含関係を効率的に判断する際に非常に役立ちます。

この定数は、DOMツリーにおけるノード間の親子や包含関係をプログラムで判定する際に使用されます。compareDocumentPosition メソッドの戻り値は、直接の真偽値ではなく、複数の状態を同時に示すビットマスクです。そのため、この定数が示す「包含している」状態を確認するには、戻り値に対してビット演算子 & を用いて比較する必要があります。また、呼び出し元のノードが引数ノードを「含んでいる」ことを示すのがこの定数であり、逆の「含まれている」状態を示す別の定数と混同しないよう、ノード間の主従関係を常に意識してください。DOMノードの取得は失敗するとnullを返すことがあるため、操作前にノードが正しく取得できているか確認することも重要です。

PHP DomDOCUMENT_POSITION_CONTAINS を使う


1<?php
2
3/**
4 * PHPのDom拡張における Dom\Node::DOCUMENT_POSITION_CONTAINS 定数の使用例。
5 * この定数は、あるDOMノードが別のノードを含んでいるかどうかを判断する際に、
6 * Dom\Node::compareDocumentPosition() メソッドの戻り値で使用されるビットマスクです。
7 *
8 * @return void
9 */
10function showDocumentPositionContainsExample(): void
11{
12    // Dom\Node::DOCUMENT_POSITION_CONTAINS 定数に関するPHPDoc形式のコメント。
13    // この定数は整数値を持ち、PHP 8のDom拡張では Dom\Node クラスに定義されています。
14    /** @var int DOCUMENT_POSITION_CONTAINS このノードが比較対象のノードを含んでいることを示すビットマスク。 */
15    echo "定数 Dom\\Node::DOCUMENT_POSITION_CONTAINS の値: " . Dom\Node::DOCUMENT_POSITION_CONTAINS . PHP_EOL;
16
17    // DOMドキュメントを作成し、サンプルHTMLを読み込む
18    $dom = new Dom\Document();
19    $dom->loadHTML('<div id="parent"><span id="child">Hello</span></div>');
20
21    // 比較対象となるノードを取得
22    $parent = $dom->getElementById('parent');
23    $child = $dom->getElementById('child');
24
25    // ノードが見つからない場合の基本的なエラーチェック
26    if ($parent === null || $child === null) {
27        echo "エラー: 必要なDOM要素（'parent' または 'child'）が見つかりませんでした。\n";
28        return;
29    }
30
31    echo "\nDom\\Node::compareDocumentPosition() を使用したノード比較の例:\n";
32
33    // 1. 'parent' ノードが 'child' ノードを含んでいるか比較する
34    // compareDocumentPosition() は、2つのノード間の相対的な位置関係を示すビットマスクを返します。
35    $comparisonResult = $parent->compareDocumentPosition($child);
36    echo "  'parent' と 'child' の比較結果ビットマスク: " . $comparisonResult . PHP_EOL;
37
38    // DOCUMENT_POSITION_CONTAINS フラグが結果に含まれているかチェック
39    if (($comparisonResult & Dom\Node::DOCUMENT_POSITION_CONTAINS) === Dom\Node::DOCUMENT_POSITION_CONTAINS) {
40        echo "  -> 結果は Dom\\Node::DOCUMENT_POSITION_CONTAINS を含んでいます ('parent' は 'child' を含んでいる)。\n";
41    } else {
42        echo "  -> 結果は Dom\\Node::DOCUMENT_POSITION_CONTAINS を含んでいません。\n";
43    }
44
45    // 2. 逆に 'child' ノードが 'parent' ノードを含んでいるか比較する
46    $comparisonResultReverse = $child->compareDocumentPosition($parent);
47    echo "  'child' と 'parent' の比較結果ビットマスク: " . $comparisonResultReverse . PHP_EOL;
48
49    if (($comparisonResultReverse & Dom\Node::DOCUMENT_POSITION_CONTAINS) === Dom\Node::DOCUMENT_POSITION_CONTAINS) {
50        echo "  -> 結果は Dom\\Node::DOCUMENT_POSITION_CONTAINS を含んでいます ('child' は 'parent' を含んでいる)。\n";
51    } else {
52        echo "  -> 結果は Dom\\Node::DOCUMENT_POSITION_CONTAINS を含んでいません ('child' は 'parent' に含まれている)。\n";
53        // 実際には、この場合は Dom\Node::DOCUMENT_POSITION_CONTAINED_BY がセットされます。
54    }
55}
56
57// 関数の実行
58showDocumentPositionContainsExample();

PHP 8のDom拡張で提供されるDom\Node::DOCUMENT_POSITION_CONTAINSは、DOM（Document Object Model）ノード間の位置関係を示す整数定数です。この定数は、特定のノードが別のノードの内部に含まれている状態を表すビットマスクとして利用されます。

主にDom\Node::compareDocumentPosition()メソッドの戻り値を解析する際に使用されます。compareDocumentPosition()メソッドは、2つのノード間の相対的な位置を示す複数の情報（ビットマスク）を返しますが、その結果にDOCUMENT_POSITION_CONTAINSが含まれているかを確認することで、一方のノードがもう一方のノードを子孫として含んでいるかを判断できます。

サンプルコードでは、div要素がその内部のspan要素を含んでいるかどうかの判定にこの定数を用いています。親となるdivノードと子となるspanノードを取得し、compareDocumentPosition()で比較した結果がDOCUMENT_POSITION_CONTAINSと一致するかを確認しています。この定数自体は引数を持たず、整数値を直接返します。これにより、HTMLやXMLドキュメントの構造をプログラムで効率的に解析し、特定の要素の包含関係を正確に把握することが可能になります。

この定数は、リファレンスにあるDom\DocumentTypeではなく、PHP 8ではDom\Nodeクラスの定数として定義されています。主にDom\Node::compareDocumentPosition()メソッドの戻り値をビット論理積演算子&と組み合わせて使用し、あるノードが別のノードを含んでいるかを効率的に判定します。

サンプルコードでは$dom->getElementById()を使用していますが、該当する要素が見つからない場合はnullが返されます。そのため、取得したノードを操作する前に、if ($parent === null)のように必ずnullチェックを行い、予期せぬエラーを防ぐようにしてください。PHPDoc形式のコメントは定数の意図や型を明確にし、コードの理解を深めるのに役立ちます。