【PHP8.x】containsメソッドの使い方

containsメソッドの使い方について、初心者にもわかりやすく解説します。

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

基本的な使い方

containsメソッドは、DOMDocumentに特定の要素が含まれているかどうかを判定するメソッドです。Dom\HTMLDocumentクラスに属しており、HTMLドキュメント内に特定の要素が存在するかどうかを確認する際に使用されます。このメソッドは、要素の存在を確認する上で重要な役割を果たし、条件分岐やエラーハンドリングなどの処理を実装する際に役立ちます。

具体的には、containsメソッドは、引数として指定された要素がドキュメント内に存在するかどうかを調べます。もし要素が存在すれば、通常はtrueを返し、存在しなければfalseを返します。この戻り値を利用することで、プログラムは要素の存在に基づいて異なる処理を実行できます。

例えば、特定のIDを持つ要素が存在するかどうかを確認し、存在する場合はその要素に対して処理を行い、存在しない場合はエラーメッセージを表示する、といった使い方が考えられます。このように、containsメソッドは、HTMLドキュメントの構造を解析し、特定の要素の存在を確認する上で非常に便利なツールとなります。

システムエンジニアを目指す初心者の方にとって、containsメソッドは、Webアプリケーション開発やスクレイピング処理など、HTMLドキュメントを扱う様々な場面で活用できる重要なメソッドです。HTMLドキュメント内の要素を効率的に検索し、必要な処理を行うための基礎となる知識として、ぜひ理解を深めてください。

構文(syntax)


1<?php
2$document = new Dom\HTMLDocument();
3$document->loadHTML('<html><body><div><p></p></div></body></html>');
4
5// チェック対象のノードを取得します
6$node = $document->getElementsByTagName('p')->item(0);
7
8// $document が $node を子孫として含んでいるかどうかの真偽値 (bool) を返します
9$result = $document->contains($node);
10?>

引数(parameters)

?Dom\Node $other

?Dom\Node $other: 検索対象のDOMノードを指定します。このノードが、現在のDom\HTMLDocument内に存在するかどうかを判定します。

戻り値(return)

bool

指定されたDOM要素が、このHTMLドキュメント内に存在するかどうかを示す真偽値を返します。存在する場合はtrue、存在しない場合はfalseを返します。

サンプルコード

PHP HTMLドキュメントのノード包含を判定する


1<?php
2
3/**
4 * Dom\HTMLDocument::contains メソッドの使用例を示します。
5 * このメソッドは、指定されたDOMノードがHTMLドキュメントツリー内に存在するかどうかを判定します。
6 */
7function demonstrateHtmlDocumentContains(): void
8{
9    // 新しいHTMLドキュメントオブジェクトを作成
10    $document = new Dom\HTMLDocument();
11
12    // サンプルHTMLコンテンツを読み込む
13    $htmlContent = '
14        <!DOCTYPE html>
15        <html>
16        <body>
17            <div id="parent">
18                <p class="child">これは子要素です。</p>
19            </div>
20            <span id="sibling">これは兄弟要素です。</span>
21        </body>
22        </html>
23    ';
24    $document->loadHTML($htmlContent);
25
26    // ドキュメントから既存のノードを取得
27    $parentNode = $document->getElementById('parent');
28    $childNode = $document->querySelector('.child'); // CSSセレクタで取得
29    $siblingNode = $document->getElementById('sibling');
30
31    // ドキュメントに追加されていない新しいノードを作成
32    // このノードはまだドキュメントツリーの一部ではありません
33    $newNodeNotInDocument = $document->createElement('div');
34    $newNodeNotInDocument->setAttribute('id', 'new-node-not-in-doc');
35
36    echo "--- Dom\\HTMLDocument::contains メソッドのテスト ---\n\n";
37
38    // ケース1: ドキュメント内に存在する親ノードのチェック
39    // HTMLドキュメントは、その中に存在する全てのノードを「含む」と判断します。
40    if ($document->contains($parentNode)) {
41        echo "✅ 'parent' div要素はドキュメントに含まれています。\n";
42    } else {
43        echo "❌ 'parent' div要素はドキュメントに含まれていません。\n";
44    }
45
46    // ケース2: ドキュメント内に存在する子ノードのチェック
47    if ($document->contains($childNode)) {
48        echo "✅ 'child' p要素はドキュメントに含まれています。\n";
49    } else {
50        echo "❌ 'child' p要素はドキュメントに含まれていません。\n";
51    }
52
53    // ケース3: ドキュメント内に存在する兄弟ノードのチェック
54    if ($document->contains($siblingNode)) {
55        echo "✅ 'sibling' span要素はドキュメントに含まれています。\n";
56    } else {
57        echo "❌ 'sibling' span要素はドキュメントに含まれていません。\n";
58    }
59
60    // ケース4: ドキュメントに追加されていない新しいノードのチェック
61    // ドキュメントオブジェクトで作成しても、まだツリーに追加されていなければ含まれていません。
62    if ($document->contains($newNodeNotInDocument)) {
63        echo "❌ 'new-node-not-in-doc' div要素はドキュメントに含まれています。\n";
64    } else {
65        echo "✅ 'new-node-not-in-doc' div要素はドキュメントに含まれていません。\n";
66    }
67
68    // ケース5: nullを引数として渡す（PHP 8の型ヒント ?Dom\Node により許容されます）
69    // nullはどのDOMツリーにも含まれないため、falseが返ります。
70    if ($document->contains(null)) {
71        echo "❌ nullはドキュメントに含まれています。\n";
72    } else {
73        echo "✅ nullはドキュメントに含まれていません。\n";
74    }
75    echo "\n";
76}
77
78// 関数を実行して結果を表示
79demonstrateHtmlDocumentContains();

PHP 8のDom\HTMLDocument::containsメソッドは、指定されたDOMノードがHTMLドキュメントの内部に存在するかどうかを判定するために使用されます。このメソッドは、$otherという引数に確認したいDom\Nodeオブジェクト、またはnullを受け取ります。ノードがドキュメントツリー内に存在する場合はtrueを、存在しない場合はfalseをブール値として返します。

サンプルコードでは、まずHTMLコンテンツをDom\HTMLDocumentに読み込み、その中に存在する親要素、子要素、兄弟要素などのノードに対してcontainsメソッドを適用しています。これらのノードはドキュメントツリーの一部であるため、メソッドはtrueを返します。一方で、createElementで新しく作成されたものの、まだドキュメントツリーに挿入されていないノードに対しては、containsメソッドはfalseを返します。これは、ノードがドキュメントオブジェクトによって作成されたとしても、実際にHTMLの構造内になければ含まれないと判断されるためです。また、引数にnullを渡した場合も、常にfalseが返されます。このメソッドは、ウェブページの構造を操作したり検証したりする際に、特定の要素が現在のドキュメントに属しているかを確認するのに役立ちます。

Dom\HTMLDocument::containsメソッドは、指定されたDOMノードがそのHTMLドキュメントの内部ツリーに実際に存在するかを判定します。ノードをcreateElementで作成しただけではドキュメントに含まれたことにならず、appendChildなどでドキュメントツリーに追加して初めてtrueが返される点にご注意ください。引数にnullを渡した場合は、常にfalseと判断されます。このメソッドはHTMLドキュメント内の要素の存在確認に特化しており、配列の要素の有無をチェックするような一般的な「含む」の用途とは文脈が異なりますので、混同しないよう注意が必要です。

PHP Dom::contains() でノード包含確認


1<?php
2
3/**
4 * Dom\HTMLDocument::contains() メソッドの使用例をデモンストレーションします。
5 * システムエンジニアを目指す初心者でも理解しやすいように、
6 * ドキュメントが特定のノードを含んでいるか、含んでいないかの両方のケースを示します。
7 *
8 * Dom\HTMLDocument::contains() は、指定されたノードが現在のドキュメントの
9 * 子孫ノードである場合に true を返します。
10 * ノードが null であるか、別のドキュメントに属しているか、
11 * まだドキュメントに追加されていない場合は false を返します。
12 */
13function demonstrateHtmlDocumentContains(): void
14{
15    echo "--- Dom\\HTMLDocument::contains() メソッドのデモンストレーション ---\n\n";
16
17    // 1. Dom\HTMLDocument オブジェクトを作成し、HTMLコンテンツをロードします
18    $htmlDocument = new Dom\HTMLDocument();
19    $htmlContent = '
20        <!DOCTYPE html>
21        <html>
22        <head>
23            <title>PHP Dom::contains 例</title>
24        </head>
25        <body>
26            <div id="main-container">
27                <p id="first-paragraph">これは最初の段落です。</p>
28                <span>これはスパン要素です。</span>
29            </div>
30            <p id="second-paragraph">これは2番目の段落です。</p>
31        </body>
32        </html>';
33
34    // HTMLコンテンツをロードします。成功すると true を返します。
35    $htmlDocument->loadHTML($htmlContent);
36
37    // 2. ドキュメント内の既存のノードを取得します
38    // getElementById() は、指定されたIDの要素が見つからない場合 null を返します。
39    $mainContainerNode = $htmlDocument->getElementById('main-container');
40    $firstParagraphNode = $htmlDocument->getElementById('first-paragraph');
41    $secondParagraphNode = $htmlDocument->getElementById('second-paragraph');
42
43    echo "=== ドキュメントに含まれるノードの確認 ===\n";
44
45    // 'main-container' ノードがドキュメントに含まれているか確認
46    if ($mainContainerNode instanceof Dom\Node) {
47        echo "ドキュメントは 'main-container' ノードを含んでいますか？ ";
48        var_dump($htmlDocument->contains($mainContainerNode)); // 期待値: true
49    } else {
50        echo "'main-container' ノードが見つかりませんでした。\n";
51    }
52
53    // 'first-paragraph' ノードがドキュメントに含まれているか確認
54    if ($firstParagraphNode instanceof Dom\Node) {
55        echo "ドキュメントは 'first-paragraph' ノードを含んでいますか？ ";
56        var_dump($htmlDocument->contains($firstParagraphNode)); // 期待値: true
57    } else {
58        echo "'first-paragraph' ノードが見つかりませんでした。\n";
59    }
60
61    // 'second-paragraph' ノードがドキュメントに含まれているか確認
62    if ($secondParagraphNode instanceof Dom\Node) {
63        echo "ドキュメントは 'second-paragraph' ノードを含んでいますか？ ";
64        var_dump($htmlDocument->contains($secondParagraphNode)); // 期待値: true
65    } else {
66        echo "'second-paragraph' ノードが見つかりませんでした。\n";
67    }
68
69    echo "\n=== ドキュメントに含まれないノードの確認 ===\n";
70
71    // 3. ドキュメントにまだ追加されていない新しいノードを作成します
72    $newDivElement = new Dom\Element('div');
73    $newDivElement->setAttribute('id', 'new-element');
74    echo "ドキュメントは 'new-element' ノード (まだドキュメントに追加されていない) を含んでいますか？ ";
75    var_dump($htmlDocument->contains($newDivElement)); // 期待値: false
76
77    // 4. 別の Dom\HTMLDocument に属するノードが現在のドキュメントに含まれないことを確認します
78    $anotherDocument = new Dom\HTMLDocument();
79    $anotherDocument->loadHTML('<body><p id="another-doc-paragraph">別のドキュメントの段落です。</p></body>');
80    $anotherDocParagraph = $anotherDocument->getElementById('another-doc-paragraph');
81
82    if ($anotherDocParagraph instanceof Dom\Node) {
83        echo "現在のドキュメントは 'another-doc-paragraph' ノード (別のドキュメントのもの) を含んでいますか？ ";
84        var_dump($htmlDocument->contains($anotherDocParagraph)); // 期待値: false
85    } else {
86        echo "'another-doc-paragraph' ノードが別のドキュメントで見つかりませんでした。\n";
87    }
88
89    // 5. contains() メソッドに null を渡した場合の挙動を確認します
90    // 引数に ?Dom\Node が許可されているため、null を渡すことが可能です。
91    echo "contains() に null を渡した場合: ";
92    var_dump($htmlDocument->contains(null)); // 期待値: false
93}
94
95// 上記のデモンストレーション関数を実行します。
96demonstrateHtmlDocumentContains();
97

Dom\HTMLDocument::contains() メソッドは、PHP 8 の DOM 拡張機能の一部で、特定のHTMLドキュメントが指定されたノードをその子孫ノードとして含んでいるかどうかを判定するために使用されます。このメソッドは、引数として ?Dom\Node 型、つまり Dom\Node オブジェクトまたは null を受け取り、結果を真偽値 (bool) で返します。

具体的には、もし指定されたノードが現在の Dom\HTMLDocument の中に実際に存在し、その一部である場合、メソッドは true を返します。例えば、HTMLドキュメントから getElementById() メソッドで取得した要素は、ドキュメントに含まれるため true となります。

一方で、以下のような場合には false を返します。まず、ドキュメントを作成したものの、まだHTMLドキュメントに追加していない新しいノードの場合です。次に、別の Dom\HTMLDocument インスタンスに属しているノードを渡した場合も false となります。これは、それぞれのドキュメントが独立したツリー構造を持つためです。さらに、引数に null を渡した場合も false が返されます。

このメソッドを使うことで、動的に操作するHTML要素が現在処理しているドキュメントに属しているかを確認でき、DOM操作のロジックをより安全に構築できます。

PHP 8のDom\HTMLDocument::contains()メソッドは、指定されたノードが現在のHTMLドキュメントのDOMツリーの子孫として存在するかを判定します。ノードがドキュメントにまだ追加されていない場合や、別のDom\HTMLDocumentに属している場合はfalseを返します。これは、ノードが現在のドキュメントの構造の一部でなければ「含まれない」と判断されるためです。引数にはnullも渡せますが、その場合もfalseが返ります。getElementByIdなどでノードを取得する際、対象要素が見つからずnullが返る可能性があるため、contains()を呼び出す前にノードが有効なDom\Nodeインスタンスであるかを確認すると、より安全で意図通りの動作を保証できます。