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

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

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

基本的な使い方

DOCUMENT_POSITION_CONTAINS定数は、PHPのDOM拡張機能において、DOMツリー内のノードが別のノードを「含んでいる」位置関係を表す定数です。

この定数は、主にDOMNodeクラスが提供するcompareDocumentPosition()メソッドの戻り値として利用されます。compareDocumentPosition()メソッドは、二つのノード間の相対的な位置関係をビットマスクの整数値として返します。この戻り値に対して、DOCUMENT_POSITION_CONTAINS定数とのビット論理積演算を行うことで、特定のノードが別のノードを子孫ノードとして含んでいるかどうかを判別できます。

具体的には、あるノードAが別のノードBを子孫ノードとして含んでいる場合、ノードAを基準としてノードBと比較した際に、compareDocumentPosition()メソッドの戻り値にはDOCUMENT_POSITION_CONTAINS定数に相当するビットがセットされます。これは、ノードAがノードBの「コンテナー」であり、ノードBがノードAの内部に存在している状態を示します。

この定数を利用することで、DOMツリーの構造を解析したり、特定の要素が別の要素の親要素や祖先要素であるかどうかのチェックを効率的に行ったりすることが可能です。例えば、あるHTML要素が別の要素の内部に配置されているかをプログラムで判断する際に、この定数が役立ちます。

構文(syntax)


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

引数(parameters)

引数なし

引数はありません

戻り値(return)

戻り値なし

戻り値はありません

サンプルコード

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


1<?php
2
3// このサンプルコードは、DOMツリーにおけるノード間の位置関係を理解するためのものです。
4// 特に、Dom\Comment オブジェクトを扱いながら、
5// Dom\Node::DOCUMENT_POSITION_CONTAINS 定数の利用方法を示します。
6// DOCUMENT_POSITION_CONTAINS 定数は Dom\Node クラスで定義されており、
7// あるノードが別のノードを含んでいるかどうかを判断する際に使用されます。
8
9// 1. 新しいDOMドキュメントを作成します。
10$document = new Dom\Document('1.0', 'UTF-8');
11$document->formatOutput = true; // 出力を整形して読みやすくします
12
13// 2. ドキュメントにルート要素（例: <body>）を追加します。
14$bodyElement = $document->createElement('body');
15$document->appendChild($bodyElement);
16
17// 3. <body>要素の子として別の要素（例: <section>）を追加します。
18$sectionElement = $document->createElement('section');
19$bodyElement->appendChild($sectionElement);
20
21// 4. Dom\Comment オブジェクトを作成します。
22$commentNode = $document->createComment('これはセクション内のコメントです');
23
24// 5. 作成したコメントノードを <section> 要素の子として追加します。
25$sectionElement->appendChild($commentNode);
26
27echo "現在のDOM構造:\n";
28echo $document->saveXML() . "\n";
29
30// 6. 親ノード ($sectionElement) が子ノード ($commentNode) を含んでいるかを確認します。
31// Dom\Node::compareDocumentPosition() メソッドは、2つのノード間の相対的な位置関係を
32// 示すビットマスク（数値の組み合わせ）を返します。
33// Dom\Node::DOCUMENT_POSITION_CONTAINS 定数は、
34// 比較対象のノード（この場合 $sectionElement）が、引数で渡されたノード（$commentNode）を
35// 含んでいる場合に、このビットがセットされます。
36$positionResult = $sectionElement->compareDocumentPosition($commentNode);
37
38// 戻り値と Dom\Node::DOCUMENT_POSITION_CONTAINS 定数をビット論理積 (&) で比較し、
39// $sectionElement が $commentNode を含んでいるか（つまり、$commentNode が $sectionElement の子であるか）
40// を確認します。
41if (($positionResult & Dom\Node::DOCUMENT_POSITION_CONTAINS) === Dom\Node::DOCUMENT_POSITION_CONTAINS) {
42    echo "--- 比較結果 ---\n";
43    echo "成功: \$sectionElement は \$commentNode を含んでいます。\n";
44    echo "これは、" . '$sectionElement->compareDocumentPosition($commentNode)' . " の結果に " . 'Dom\Node::DOCUMENT_POSITION_CONTAINS' . " が含まれているためです。\n";
45} else {
46    echo "--- 比較結果 ---\n";
47    echo "エラー: \$sectionElement は \$commentNode を含んでいません。\n";
48}
49
50// 別の比較例: コメントノードがドキュメントを含んでいるか？
51// (実際にはコメントノードはドキュメントに「含まれる」側なので、DOCUMENT_POSITION_CONTAINS はセットされません。)
52$positionInverse = $commentNode->compareDocumentPosition($document);
53if (($positionInverse & Dom\Node::DOCUMENT_POSITION_CONTAINS) === Dom\Node::DOCUMENT_POSITION_CONTAINS) {
54    echo "--- 逆方向の比較結果 ---\n";
55    echo "誤った結果: \$commentNode は \$document を含んでいます。\n";
56} else {
57    echo "--- 逆方向の比較結果 ---\n";
58    echo "正しい結果: \$commentNode は \$document を含んでいません。\n";
59    // 補足: この場合、$commentNode は $document に含まれているため、
60    // $positionInverse には Dom\Node::DOCUMENT_POSITION_CONTAINED_BY がセットされます。
61}
62

このPHPのサンプルコードは、DOMツリー内におけるノード間の位置関係を理解するためのものです。特に、Dom\Nodeクラスで定義されている定数DOCUMENT_POSITION_CONTAINSの利用方法を紹介しています。この定数は、あるノードが別のノードを含んでいるかどうか、つまり親子の関係にあるかを判断する際に使用されます。

コードではまず、新しいDOMドキュメントを作成し、<body>要素や<section>要素、そしてDom\Commentオブジェクト（HTMLコメントノード）をツリーに追加していきます。そして、<section>要素の子としてコメントノードを配置します。

次に、親ノードである$sectionElementが子ノードである$commentNodeを含んでいるかを確認するために、$sectionElement->compareDocumentPosition($commentNode)メソッドを呼び出します。このcompareDocumentPosition()メソッドは、二つのノード間の相対的な位置関係を示す数値（ビットマスク）を戻り値として返します。DOCUMENT_POSITION_CONTAINS定数は、比較対象のノード（ここでは$sectionElement）が、引数で渡されたノード（$commentNode）を含んでいる場合に、その戻り値の数値の中に特定のビットがセットされることを示します。

サンプルコードでは、このcompareDocumentPosition()メソッドの戻り値とDom\Node::DOCUMENT_POSITION_CONTAINS定数をビット論理積(&)で比較し、$sectionElementが$commentNodeを含んでいるか（親であるか）を正確に判定しています。この定数自体は引数を取らず、戻り値もありませんが、compareDocumentPosition()メソッドの戻り値と組み合わせることで、DOMツリーの構造をプログラムで確認する際に非常に重要な役割を果たします。

Dom\Node::DOCUMENT_POSITION_CONTAINS定数は、DOMノード間の親子関係を判断する際に使われます。この定数はDom\Nodeクラスで定義されており、Dom\CommentオブジェクトもDom\Nodeを継承しているため、利用できます。最も重要な注意点は、compareDocumentPosition()メソッドの戻り値は複数の状態を示すビットマスクのため、定数との比較にはビット論理積&を必ず用いてください。また、この定数は、メソッドを呼び出す側のノードが引数のノードを「含んでいる」か（親であるか）を判定しますので、ノードの順序と親子関係の理解が重要です。この点を誤ると、意図しない結果を招く可能性があります。

PHP DOM Comment 定数でノード包含を判定する


1<?php
2
3/**
4 * Dom\Comment クラスの文脈で DOM ノードの位置関係を比較する定数
5 * Dom\Node::DOCUMENT_POSITION_CONTAINS の使用例を示します。
6 *
7 * この定数は、PHP 8 の新しい Dom 拡張で使用されるもので、
8 * あるノードが別のノードを包含しているかどうかを判定するために利用されます。
9 *
10 * 注: DOCUMENT_POSITION_CONTAINS 定数自体は Dom\Node クラスに定義されています。
11 * Dom\Comment は Dom\Node を継承しているため、Dom\Comment オブジェクトを操作する際に
12 * Dom\Node の定数を参照して利用することができます。
13 */
14function demonstrateDocumentPositionContainsForCommentContext(): void
15{
16    // 新しい Dom\Document オブジェクトを作成します。
17    $document = new Dom\Document();
18    // HTML をロードしてノードツリーを構築します。
19    $document->loadHTML('<root><parent><child></child></parent></root>');
20
21    // ドキュメント内の要素ノードを取得します。
22    $root = $document->documentElement;     // <root>
23    $parent = $root->firstChild;           // <parent>
24    $child = $parent->firstChild;          // <child>
25
26    // Dom\Comment ノードを作成し、親ノードに追加します。
27    $comment = new Dom\Comment('これはコメントです');
28    $parent->appendChild($comment);
29
30    echo "--- DOM ノードの位置関係の比較 ---" . PHP_EOL;
31
32    // 1. parent ノードが child ノードを包含しているか確認します。
33    // compareDocumentPosition() は、2つのノード間の位置関係を示すビットマスクを返します。
34    $positionOfChildInParent = $parent->compareDocumentPosition($child);
35
36    echo "parent と child の比較結果: " . $positionOfChildInParent . PHP_EOL;
37    // ビット演算子 '&' を使用して、返された値に DOCUMENT_POSITION_CONTAINS が含まれているか確認します。
38    if ($positionOfChildInParent & Dom\Node::DOCUMENT_POSITION_CONTAINS) {
39        echo "  -> parent ノードは child ノードを包含しています。" . PHP_EOL;
40    } else {
41        echo "  -> parent ノードは child ノードを包含していません。" . PHP_EOL;
42    }
43
44    // 2. parent ノードが comment ノードを包含しているか確認します。
45    // Dom\Comment も Dom\Node を継承しているため、同様に比較できます。
46    $positionOfCommentInParent = $parent->compareDocumentPosition($comment);
47
48    echo "parent と comment の比較結果: " . $positionOfCommentInParent . PHP_EOL;
49    if ($positionOfCommentInParent & Dom\Node::DOCUMENT_POSITION_CONTAINS) {
50        echo "  -> parent ノードは comment ノードを包含しています。" . PHP_EOL;
51    } else {
52        echo "  -> parent ノードは comment ノードを包含していません。" . PHP_EOL;
53    }
54
55    // 3. comment ノードが parent ノードに包含されているか確認します。
56    // 逆の比較では、DOCUMENT_POSITION_CONTAINED_BY が使用されます。
57    $positionOfParentInComment = $comment->compareDocumentPosition($parent);
58
59    echo "comment と parent の比較結果: " . $positionOfParentInComment . PHP_EOL;
60    if ($positionOfParentInComment & Dom\Node::DOCUMENT_POSITION_CONTAINED_BY) {
61        echo "  -> comment ノードは parent ノードに包含されています。" . PHP_EOL;
62    } else {
63        echo "  -> comment ノードは parent ノードに包含されていません。" . PHP_EOL;
64    }
65}
66
67// 定数の利用例を示す関数を実行します。
68demonstrateDocumentPositionContainsForCommentContext();

PHP 8で導入されたDom拡張機能におけるDom\Node::DOCUMENT_POSITION_CONTAINS定数は、DOM（Document Object Model）ツリー上のノード間で「あるノードが別のノードを包含しているか」という位置関係を判定するために利用されます。この定数自体はDom\Nodeクラスに定義されていますが、Dom\CommentクラスもDom\Nodeを継承しているため、Dom\Commentオブジェクトを操作する際にもこの定数を使ってノード間の位置関係を比較できます。

サンプルコードでは、まずDom\DocumentオブジェクトにHTMLをロードしてノードツリーを構築し、その後、新しいDom\Commentノードを作成して既存の親ノードに追加しています。そして、Dom\Nodeクラスが持つcompareDocumentPosition()メソッドを用いて、これらのノード間の位置関係を調べています。このメソッドは、引数に比較対象のDom\Nodeオブジェクトを受け取り、戻り値としてノード間の位置関係を示す整数値（ビットマスク）を返します。

返されたビットマスクとDom\Node::DOCUMENT_POSITION_CONTAINS定数をビット演算子&で組み合わせることで、「親ノードが子ノードを包含しているか」といった具体的な包含関係を正確に判定できます。サンプルでは、親ノードが子ノードやコメントノードを包含しているかの確認に加え、コメントノードが親ノードに包含されているかをDOCUMENT_POSITION_CONTAINED_BY定数を利用して調べる例も示されており、複雑なDOMツリー内でのノード配置を理解するのに役立ちます。

DOCUMENT_POSITION_CONTAINS定数は、Dom\Nodeクラスに定義されており、Dom\Commentクラスがこれを継承しているため、コメントノードを含むDOMノード間の包含関係を判定する際に利用できます。この定数自体が何かを直接返すのではなく、Dom\NodeのcompareDocumentPosition()メソッドの戻り値とビット論理積（&）を使って、比較結果を解釈するために用います。サンプルコードのようにDom\Node::DOCUMENT_POSITION_CONTAINSと指定して利用することが一般的です。ノードが「包含されている」かを判定する際にはDOCUMENT_POSITION_CONTAINED_BYなどの関連定数も存在しますので、混同しないよう注意が必要です。この機能はPHP 8以降の新しいDOM拡張で導入されました。