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

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

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

基本的な使い方

DOCUMENT_POSITION_CONTAINS定数は、PHPのDOM拡張機能において、二つのノード間の相対的な位置関係を比較する際に使用される定数の一つです。この定数は、主にDOMNodeクラスが提供するcompareDocumentPosition()メソッドの戻り値として利用されます。

compareDocumentPosition()メソッドは、ある基準となるノードに対して、別の比較対象ノードが文書構造の中でどのような位置関係にあるかを示すビットマスク値を返します。この戻り値がDOCUMENT_POSITION_CONTAINS定数の値を含んでいる場合、それは比較対象のノードが基準となるノードを「含んでいる」状態であることを意味します。具体的には、基準ノードが比較対象ノードの子孫ノードである、あるいは比較対象ノード自身であるといった包含関係を示します。

例えば、HTML文書において<body>要素と、その<body>要素内に存在する<div>要素を比較する状況を想像してみてください。もし<body>要素を比較対象ノード、<div>要素を基準ノードとしてcompareDocumentPosition()メソッドを実行した場合、<body>要素は<div>要素を含んでいるため、返される値にはDOCUMENT_POSITION_CONTAINS定数の値が含まれることになります。

この定数は、XMLやHTMLなどのマークアップ言語で記述された文書の構造（DOMツリー）をプログラムで解析したり操作したりする際に、特定の要素が別の要素の内部に存在するかどうかを効率的かつ正確に判断するために非常に重要な役割を果たします。文書ツリーにおける親子関係や包含関係を論理的に処理する上で、欠かせない情報を提供するものです。

構文(syntax)


1<?php
2echo DOMDocument::DOCUMENT_POSITION_CONTAINS;

引数(parameters)

引数なし

引数はありません

戻り値(return)

int

DOMDocument::DOCUMENT_POSITION_CONTAINSは、あるノードが別のノードに含まれていることを示す整数値1を返します。

サンプルコード

PHP DOM Objectでノード包含位置を確認する


1<?php
2
3/**
4 * DOMDocument::DOCUMENT_POSITION_CONTAINS 定数の使用例を示します。
5 * この定数は、DOMNode::compareDocumentPosition() メソッドが返す値の一部で、
6 * あるノードが別のノードを含んでいる（親である）ことを示します。
7 *
8 * システムエンジニアを目指す初心者向けに、XML/HTML ドキュメント内の要素の親子関係を
9 * プログラムで確認する方法を簡潔に示します。
10 */
11function demonstrateDomContainsPosition(): void
12{
13    // 1. DOMDocument オブジェクトを作成します。
14    // これにより、HTMLやXMLドキュメントをPHPで操作できるようになります。
15    $dom = new DOMDocument();
16
17    // 2. HTML 文字列を読み込みます。
18    // loadHTML() はHTMLを解析し、DOMツリーを構築します。
19    // @ はエラー出力抑制演算子で、解析エラーを画面に出さなくします（実運用ではエラーログを確認すべきです）。
20    $htmlContent = '<html><body><div id="parent"><span id="child">Hello DOM</span></div></body></html>';
21    @$dom->loadHTML($htmlContent);
22
23    // 3. 比較対象となる2つの DOMNode オブジェクト（要素）を取得します。
24    // DOMXPath は、XMLドキュメント内で特定の要素を検索するための強力なツールです。
25    $xpath = new DOMXPath($dom);
26
27    // id="parent" の div 要素を取得します。これが親ノードの候補です。
28    $parentNode = $xpath->query('//div[@id="parent"]')->item(0);
29
30    // id="child" の span 要素を取得します。これが子ノードの候補です。
31    $childNode = $xpath->query('//span[@id="child"]')->item(0);
32
33    // ノードが見つからなかった場合は処理を中断します。
34    if ($parentNode === null || $childNode === null) {
35        echo "エラー: 必要な親ノードまたは子ノードが見つかりませんでした。\n";
36        return;
37    }
38
39    echo "--- DOMDocument::DOCUMENT_POSITION_CONTAINS デモンストレーション ---\n\n";
40
41    // 4. parentNode が childNode を含んでいるか（親であるか）を比較します。
42    // DOMNode::compareDocumentPosition() は、2つのノード間の位置関係を示す整数値（ビットマスク）を返します。
43    // 例えば、参照ノードが引数のノードを含んでいる場合、DOCUMENT_POSITION_CONTAINS のビットがセットされます。
44    $position = $parentNode->compareDocumentPosition($childNode);
45
46    echo "比較対象: 親ノード ('div#parent') と子ノード ('span#child')\n";
47    echo "compareDocumentPosition() の結果 (ビットマスク): " . $position . "\n";
48
49    // 5. 結果を DOMDocument::DOCUMENT_POSITION_CONTAINS 定数と比較し、含んでいるかを判断します。
50    // ビット AND 演算子 (&) を使い、特定の位置関係のビットが立っているかを確認します。
51    if (($position & DOMDocument::DOCUMENT_POSITION_CONTAINS) === DOMDocument::DOCUMENT_POSITION_CONTAINS) {
52        echo "結論: 親ノード ('div#parent') は子ノード ('span#child') を含んでいます。\n";
53    } else {
54        echo "結論: 親ノード ('div#parent') は子ノード ('span#child') を含んでいません。\n";
55    }
56
57    echo "\n--- 逆の比較例 ---\n";
58
59    // 逆の比較: 子ノードが親ノードを含んでいるか
60    // （通常、子は親を含まないので、この場合は「含んでいない」と表示されるはずです）
61    $reversePosition = $childNode->compareDocumentPosition($parentNode);
62    echo "比較対象: 子ノード ('span#child') と親ノード ('div#parent')\n";
63    echo "compareDocumentPosition() の結果 (ビットマスク): " . $reversePosition . "\n";
64
65    if (($reversePosition & DOMDocument::DOCUMENT_POSITION_CONTAINS) === DOMDocument::DOCUMENT_POSITION_CONTAINS) {
66        echo "結論: 子ノード ('span#child') は親ノード ('div#parent') を含んでいます。\n";
67    } else {
68        echo "結論: 子ノード ('span#child') は親ノード ('div#parent') を含んでいません。\n";
69    }
70}
71
72// 上記で定義した関数を実行します。
73demonstrateDomContainsPosition();
74
75?>

このサンプルコードは、PHPのDOM拡張機能を利用し、HTMLやXMLドキュメント内の要素の親子関係をプログラムで確認する方法を示しています。特に、DOMDocument::DOCUMENT_POSITION_CONTAINS定数を使用して、あるノードが別のノードを含んでいる（親である）かを判定します。

まず、DOMDocumentオブジェクトを生成し、HTML文字列を読み込むことで、ドキュメント構造をPHPで操作できる形に変換します。次に、DOMXPathというツールを使って、特定のIDを持つ親ノードと子ノードを取得します。

要素間の位置関係を比較する際に使用するのが、DOMNode::compareDocumentPosition()メソッドです。このメソッドは、2つのノード間のさまざまな位置関係を示す整数値（ビットマスク）を返します。この戻り値は、複数の状態を同時に表現する特別な数値です。DOMDocument::DOCUMENT_POSITION_CONTAINS定数（戻り値はint型）は、このビットマスクの中で「参照ノードが引数のノードを含んでいる」という特定の状態を示す値です。

サンプルコードでは、compareDocumentPosition()メソッドの戻り値とDOCUMENT_POSITION_CONTAINS定数をビットAND演算子&で比較しています。これにより、戻り値の数値の中に「含んでいる」という状態のビットが立っているか、つまり親ノードが子ノードを実際に含んでいるかを正確に判断できます。この定数を活用することで、複雑なHTML/XMLドキュメントの構造をプログラムで理解し、要素間の関係性を効率的に判定できるようになります。

このサンプルコードでは、HTML解析にDOMDocumentを使用していますが、@演算子でのエラー抑制は開発時に限定し、本番環境ではエラーログを確認するようにしてください。DOMNode::compareDocumentPosition()メソッドはビットマスクを返すため、特定の状態を判定するにはDOCUMENT_POSITION_CONTAINS定数とのビットAND演算子&が不可欠です。DOMXPathは要素検索に便利ですが、XPath構文の理解が必要です。query()の結果は常にitem(0)で取得する前に、nullチェックを行い、ノードが存在しない場合の処理を適切に行うことが重要です。これらの点に注意し、安全にDOM操作を行いましょう。

PHP DOMDocument::DOCUMENT_POSITION_CONTAINS を使う


1<?php
2
3/**
4 * DOMDocument::DOCUMENT_POSITION_CONTAINS 定数の使用例をデモンストレーションします。
5 *
6 * この定数は、DOMNode::compareDocumentPosition() メソッドと共に使用される整数値です。
7 * 参照ノードが比較対象のノードを含んでいる場合に、結果のビットマスクに含まれます。
8 *
9 * @see https://www.php.net/manual/ja/class.domdocument.php
10 * @see https://www.php.net/manual/ja/domnode.comparedocumentposition.php
11 */
12function demonstrateDocumentPositionContains(): void
13{
14    // DOMDocument::DOCUMENT_POSITION_CONTAINS 定数の値と型を表示します。
15    // これは、他のノードを「含む」位置関係を示すビットマスクの一部です。
16    echo "DOMDocument::DOCUMENT_POSITION_CONTAINS の値: " . DOMDocument::DOCUMENT_POSITION_CONTAINS . PHP_EOL;
17    echo "DOMDocument::DOCUMENT_POSITION_CONTAINS の型: " . gettype(DOMDocument::DOCUMENT_POSITION_CONTAINS) . PHP_EOL . PHP_EOL;
18
19    // XMLドキュメントを作成し、DOMツリーを構築します。
20    $dom = new DOMDocument();
21    $dom->loadXML('<root><parent><child id="c1"/></parent><sibling id="s1"/></root>');
22
23    // 比較するノードを取得します。
24    $rootNode = $dom->documentElement; // <root>
25    $parentNode = $dom->getElementsByTagName('parent')->item(0); // <parent>
26    $childNode = $dom->getElementById('c1'); // <child id="c1"/>
27    $siblingNode = $dom->getElementById('s1'); // <sibling id="s1"/>
28
29    if ($rootNode && $parentNode && $childNode && $siblingNode) {
30
31        echo "--- ノードの位置関係の比較 ---" . PHP_EOL;
32
33        // 例1: rootNode は parentNode を含む
34        // $rootNode が $parentNode を含んでいるかをチェックします。
35        $positionResult1 = $rootNode->compareDocumentPosition($parentNode);
36        echo " '<root>' と '<parent>' の比較結果: " . $positionResult1 . PHP_EOL;
37        if (($positionResult1 & DOMDocument::DOCUMENT_POSITION_CONTAINS) === DOMDocument::DOCUMENT_POSITION_CONTAINS) {
38            echo "   -> '<root>' は '<parent>' を含んでいます。(期待通り)" . PHP_EOL;
39        } else {
40            echo "   -> '<root>' は '<parent>' を含んでいません。(予期せず)" . PHP_EOL;
41        }
42        echo PHP_EOL;
43
44        // 例2: parentNode は childNode を含む
45        // $parentNode が $childNode を含んでいるかをチェックします。
46        $positionResult2 = $parentNode->compareDocumentPosition($childNode);
47        echo " '<parent>' と '<child>' の比較結果: " . $positionResult2 . PHP_EOL;
48        if (($positionResult2 & DOMDocument::DOCUMENT_POSITION_CONTAINS) === DOMDocument::DOCUMENT_POSITION_CONTAINS) {
49            echo "   -> '<parent>' は '<child>' を含んでいます。(期待通り)" . PHP_EOL;
50        } else {
51            echo "   -> '<parent>' は '<child>' を含んでいません。(予期せず)" . PHP_EOL;
52        }
53        echo PHP_EOL;
54
55        // 例3: parentNode は siblingNode を含まない (兄弟ノードのため)
56        // $parentNode が $siblingNode を含んでいるかをチェックします。
57        $positionResult3 = $parentNode->compareDocumentPosition($siblingNode);
58        echo " '<parent>' と '<sibling>' の比較結果: " . $positionResult3 . PHP_EOL;
59        if (($positionResult3 & DOMDocument::DOCUMENT_POSITION_CONTAINS) === DOMDocument::DOCUMENT_POSITION_CONTAINS) {
60            echo "   -> '<parent>' は '<sibling>' を含んでいます。(予期せず)" . PHP_EOL;
61        } else {
62            echo "   -> '<parent>' は '<sibling>' を含んでいません。(期待通り)" . PHP_EOL;
63        }
64
65    } else {
66        echo "エラー: XMLのロードまたはノードの取得に失敗しました。" . PHP_EOL;
67    }
68}
69
70// 関数を実行してデモンストレーションを開始します。
71demonstrateDocumentPositionContains();

DOMDocument::DOCUMENT_POSITION_CONTAINSは、PHPのDOM（Document Object Model）拡張機能で使用される整数値の定数です。この定数は、DOMツリー内におけるノード間の位置関係、特に「あるノードが別のノードを含んでいるか」をプログラムで判定する際に役立ちます。引数はなく、常に固定の整数値を返します。

この定数は、主にDOMNode::compareDocumentPosition()メソッドの戻り値と組み合わせて利用されます。compareDocumentPosition()メソッドは、比較対象のノードに対する参照ノードの位置関係を、様々な状態を示すビットマスクとして整数で返します。DOMDocument::DOCUMENT_POSITION_CONTAINS定数の値と、このメソッドの戻り値をビット論理AND演算子（&）で比較することで、参照ノードが比較対象ノードを子孫として含んでいるかを正確に判断できます。

サンプルコードでは、XMLドキュメントから複数のノードを取得し、それらの位置関係を比較しています。例えば、ルートノードである<root>がその子要素である<parent>を含む場合や、<parent>が<child>を含む場合には、比較結果にDOCUMENT_POSITION_CONTAINSが含まれることが示されます。一方、<parent>が自身の兄弟要素である<sibling>を含まない場合は、この定数は結果に含まれません。このように、DOMツリー構造におけるノードの包含関係をプログラムで効率的に確認するために、この定数は重要な役割を果たします。

この定数は、DOMツリー内のノードが互いを「含んでいるか」という位置関係を判定するために使用します。単体で使うのではなく、DOMNode::compareDocumentPosition() メソッドが返す整数値（ビットマスク）と、ビット論理積演算子 & を用いて比較することが重要です。これは、複数の状態を表すビットフラグの中から「含む」という特定のフラグが立っているかを確認する操作です。DOMツリーの構造を理解し、親ノードが子ノードや子孫ノードを含む関係を正しく把握することが利用の前提となります。また、サンプルコードのように getElementById() でノードを取得する際は、対象のXML/HTML文書内でIDが一意に定義されていることを確認してください。