いっしー@Webエンジニア
Webツールプログラミング言語プログラミング学習ITニュースIT用語辞典ポートフォリオ
Webエンジニア向けプログラミング解説動画をYouTubeで配信中！
▶ チャンネル登録はこちら

【PHP8.x】Dom\HTMLElement::contains()メソッドの使い方

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

作成日: 更新日:

基本的な使い方

containsメソッドは、DOM要素が指定されたノード（要素）を包含しているかどうかを確認するメソッドです。Dom\HTMLElementクラスに属しており、PHPのDOM拡張モジュールで使用されます。具体的には、このメソッドは、対象となるDOM要素が、引数として渡されたノードの親、祖先にあたるかどうかを判定します。

メソッドは、引数としてDOMNodeオブジェクトを受け取ります。このDOMNodeオブジェクトは、包含関係を確認したいノードを表します。

containsメソッドの戻り値はboolean型です。対象となるDOM要素が指定されたノードを包含している場合はtrueを、そうでない場合はfalseを返します。

このメソッドは、DOMツリー構造における要素間の関係性をプログラム的に判断するために非常に役立ちます。例えば、特定の要素の子要素、あるいはそれより深い階層にある要素であるかを判定する際に利用できます。ウェブページの特定の部分が、特定の要素内に存在するかどうかを検証するような場合に便利です。

containsメソッドを使用することで、複雑なDOM構造を効率的に操作し、特定の条件を満たす要素を特定する処理などを実装できます。

構文(syntax)

1public Dom\HTMLElement::contains(Dom\HTMLElement $other): bool

引数(parameters)

?Dom\Node $other

  • ?Dom\Node $other: 比較対象となるDOMノード。指定されたノードが現在のノードのツリー内に存在するかどうかを確認します。NULLを指定した場合、FALSEを返します。

戻り値(return)

bool

指定された要素がこの要素の子孫に含まれているかどうかを真偽値（true または false）で返します。

サンプルコード

PHP: Dom\HTMLElement::contains()で子孫要素を判定する

1<?php
2
3/**
4 * Dom\HTMLElement::contains() メソッドの使用例を示します。
5 * このメソッドは、あるHTML要素が別のHTML要素を子孫として含んでいるかを判定します。
6 */
7function checkHtmlElementContainment(): void
8{
9    // 新しいDOMドキュメントを作成します。
10    $dom = new Dom\Document();
11
12    // 親となる<div>要素を作成し、ドキュメントに追加します。
13    $parentDiv = new Dom\HTMLElement('div');
14    $parentDiv->setAttribute('id', 'parent-div');
15    $dom->appendChild($parentDiv);
16
17    // 子となる<span>要素を作成し、親要素に追加します。
18    $childSpan = new Dom\HTMLElement('span');
19    $childSpan->setAttribute('id', 'child-span');
20    $parentDiv->appendChild($childSpan);
21
22    // もう一つの子となる<p>要素を作成し、親要素に追加します。
23    $anotherChildP = new Dom\HTMLElement('p');
24    $anotherChildP->setAttribute('id', 'another-child-p');
25    $parentDiv->appendChild($anotherChildP);
26
27    // ドキュメントには追加されていない独立した<button>要素を作成します。
28    $independentButton = new Dom\HTMLElement('button');
29    $independentButton->setAttribute('id', 'independent-button');
30
31    echo "--- Dom\\HTMLElement::contains() の使用例 ---\n";
32
33    // parentDiv が childSpan を含むかチェック (期待値: true)
34    echo "parent-div が child-span を含みますか？ "
35        . ($parentDiv->contains($childSpan) ? "はい" : "いいえ") . "\n";
36
37    // childSpan が parentDiv を含むかチェック (期待値: false)
38    echo "child-span が parent-div を含みますか？ "
39        . ($childSpan->contains($parentDiv) ? "はい" : "いいえ") . "\n";
40
41    // parentDiv が anotherChildP を含むかチェック (期待値: true)
42    echo "parent-div が another-child-p を含みますか？ "
43        . ($parentDiv->contains($anotherChildP) ? "はい" : "いいえ") . "\n";
44
45    // childSpan が anotherChildP を含むかチェック (期待値: false)
46    echo "child-span が another-child-p を含みますか？ "
47        . ($childSpan->contains($anotherChildP) ? "はい" : "いいえ") . "\n";
48
49    // 要素が自分自身を含むかチェック (期待値: true)
50    echo "parent-div が parent-div 自身を含みますか？ "
51        . ($parentDiv->contains($parentDiv) ? "はい" : "いいえ") . "\n";
52
53    // ドキュメントに存在しない、または関連のない要素を含むかチェック (期待値: false)
54    echo "parent-div が independent-button を含みますか？ "
55        . ($parentDiv->contains($independentButton) ? "はい" : "いいえ") . "\n";
56
57    // nullを引数に渡した場合のチェック (期待値: false)
58    echo "parent-div が null を含みますか？ "
59        . ($parentDiv->contains(null) ? "はい" : "いいえ") . "\n";
60}
61
62// 関数を実行します。
63checkHtmlElementContainment();

PHPのDom\HTMLElement::contains()メソッドは、特定のHTML要素（メソッドを呼び出す元の要素）が、別の指定されたHTML要素（引数で渡される要素）を子孫として含んでいるかを判定するために使用されます。このメソッドは、WebページのDOM（Document Object Model）構造をプログラム上で確認する際に非常に役立ちます。

引数には?Dom\Node $otherを受け取ります。これは、呼び出し元の要素に含まれているかを確認したい対象のHTML要素または他のDOMノードを指定します。nullを渡すことも可能です。戻り値はbool型で、呼び出し元の要素が引数で指定された要素を子孫（直接の子要素だけでなく、孫要素なども含む）として含んでいる場合はtrueを、そうでない場合はfalseを返します。なお、要素が自分自身を含んでいる場合もtrueと判定されます。

サンプルコードでは、Dom\Documentと複数のDom\HTMLElementを作成し、それらの間に親子の階層関係を構築しています。その上で、parentDivがchildSpanやanotherChildPといった子孫要素を含んでいるか、childSpanがparentDivを含まないか、またドキュメントに属さないindependentButtonやnullを渡した場合にどのように判定されるかをcontains()メソッドで確認し、その結果を出力しています。これにより、HTML要素の論理的な包含関係を簡単に検証できることが示されています。このメソッドは、配列の要素の有無をチェックする一般的な「contains」とは異なり、HTMLのDOM構造における親子関係に特化している点にご注意ください。

Dom\HTMLElement::contains()は、HTML要素が別のHTML要素を子孫として含んでいるか（自分自身も含む）を判定するメソッドです。これは配列内の値やキーの存在をチェックする機能とは異なり、HTMLのDOMツリー構造における親子関係に特化している点に注意してください。

引数にはDom\Node型のオブジェクト、またはnullを渡す必要があります。それ以外の型を渡すと型エラーとなりプログラムが停止する可能性があるため、常に適切な型の引数を与えるようにしましょう。また、DOMツリーに接続されていない要素同士を比較しても、通常は含まないと判断されます。引数にnullを渡した場合は、常にfalseが返されます。利用する際は、引数の型と要素がDOMツリー内で正しく接続されているかを確認することが安全な利用に繋がります。

PHP Dom\HTMLElement::contains() メソッドで要素の包含関係を判定する

1<?php
2
3/**
4 * Dom\HTMLElement::contains() メソッドの使用例を示します。
5 *
6 * この関数は、HTML DOM構造を構築し、ある要素が別の要素を
7 * 含んでいるかどうかを Dom\HTMLElement::contains() メソッドで判定する方法を
8 * システムエンジニアを目指す初心者にも分かりやすくデモンストレーションします。
9 *
10 * 注意: このコードは PHP 8.2 以降で導入された新しい DOM API を使用しています。
11 * Dom\HTMLElement クラスはそれ以前のバージョンでは利用できません。
12 */
13function demonstrateDomContainsMethod(): void
14{
15    // ① HTML ドキュメントの準備
16    // Dom\Document オブジェクトを作成し、テスト用のHTMLコンテンツをロードします。
17    // loadHTML() は無効なHTMLで警告を出すことがありますが、サンプルでは @ で抑制しています。
18    // 実際のアプリケーションでは、エラーハンドリングを適切に行うことを推奨します。
19    $dom = new \Dom\Document();
20    $htmlContent = <<<HTML
21<!DOCTYPE html>
22<html>
23<head>
24    <title>DOM Contains Example</title>
25</head>
26<body>
27    <div id="container-element">
28        <p id="parent-element">
29            <span>Nested Span</span>
30            <a id="child-element">Nested Link</a>
31        </p>
32        <div id="sibling-element">Sibling Div</div>
33    </div>
34</body>
35</html>
36HTML;
37    @$dom->loadHTML($htmlContent);
38
39    // ② Dom\HTMLElement オブジェクトの取得
40    // CSSセレクタを使って、テスト対象となるHTML要素を Dom\HTMLElement オブジェクトとして取得します。
41    // querySelector() は指定されたセレクタに一致する最初の要素を返します。
42    $containerElement = $dom->querySelector('#container-element');
43    $parentElement = $dom->querySelector('#parent-element');
44    $childElement = $dom->querySelector('#child-element');
45    $siblingElement = $dom->querySelector('#sibling-element');
46    $nonExistentElement = $dom->querySelector('#non-existent'); // 存在しない要素を取得しようとした場合、nullが返ります
47
48    // 取得した要素が期待通り Dom\HTMLElement のインスタンスであることを確認します。
49    // 何らかの理由で要素が見つからなかった場合（例: セレクタの誤り）、スクリプトを中断します。
50    if (!$parentElement instanceof \Dom\HTMLElement ||
51        !$childElement instanceof \Dom\HTMLElement ||
52        !$siblingElement instanceof \Dom\HTMLElement ||
53        !$containerElement instanceof \Dom\HTMLElement) {
54        echo "エラー: 必要な Dom\\HTMLElement 要素の一部または全てを取得できませんでした。\n";
55        echo "PHP 8.2 以降の DOM API と、有効なHTML構造が正しくロードされているか確認してください。\n";
56        return;
57    }
58
59    echo "--- Dom\\HTMLElement::contains() メソッドの使用例 ---\n\n";
60
61    // ケース1: 親要素がその直接の子要素を含んでいるか
62    $result1 = $parentElement->contains($childElement);
63    echo "1. '#parent-element' は '#child-element' を含みますか？ " . ($result1 ? "はい" : "いいえ") . "\n";
64    // 期待値: はい (子要素は常に親要素に含まれます)
65
66    // ケース2: ある要素が自分自身を含んでいるか
67    $result2 = $parentElement->contains($parentElement);
68    echo "2. '#parent-element' はそれ自身を含みますか？ " . ($result2 ? "はい" : "いいえ") . "\n";
69    // 期待値: はい (contains() メソッドは、対象要素が自分自身を含むと見なします)
70
71    // ケース3: ある要素がその兄弟要素を含んでいるか
72    $result3 = $parentElement->contains($siblingElement);
73    echo "3. '#parent-element' は '#sibling-element' を含みますか？ " . ($result3 ? "はい" : "いいえ") . "\n";
74    // 期待値: いいえ (兄弟要素は同じ親を持つが、互いには含まれません)
75
76    // ケース4: 祖先要素が子孫要素を含んでいるか
77    $result4 = $containerElement->contains($childElement);
78    echo "4. '#container-element' は '#child-element' を含みますか？ " . ($result4 ? "はい" : "いいえ") . "\n";
79    // 期待値: はい (祖先要素は、直接的であるかどうかにかかわらず、その全ての子孫要素を含みます)
80
81    // ケース5: 存在しない要素（null）を引数として渡した場合
82    // contains() メソッドの引数は `?Dom\Node` であり、nullも受け入れます。
83    $result5 = $parentElement->contains($nonExistentElement);
84    echo "5. '#parent-element' は存在しない要素（null）を含みますか？ " . ($result5 ? "はい" : "いいえ") . "\n";
85    // 期待値: いいえ (null はどの要素にも含まれません)
86
87    // ケース6: 子要素がその親要素を含んでいるか
88    $result6 = $childElement->contains($parentElement);
89    echo "6. '#child-element' は '#parent-element' を含みますか？ " . ($result6 ? "はい" : "いいえ") . "\n";
90    // 期待値: いいえ (子要素が親要素を含むことはありません)
91}
92
93// デモンストレーション関数を実行します。
94demonstrateDomContainsMethod();
95

PHP 8.2以降で導入されたDom\HTMLElement::contains()メソッドは、ウェブページのHTML要素の包含関係をプログラムで確認する際に使用されます。このメソッドは、あるHTML要素（例えば親となるdiv要素）が、別の特定のHTML要素（例えばその中のp要素やa要素）を含んでいるかどうかを判定し、結果を真偽値（trueまたはfalse）で返します。

使い方は、包含関係を調べたい元のDom\HTMLElementオブジェクトからcontains()を呼び出し、引数として比較したい対象のDom\Nodeオブジェクト、またはnullを渡します。もし元の要素が引数に指定された要素を「含んでいれば」trueが返され、含んでいなければfalseが返されます。この「含む」とは、子要素や孫要素などのすべての子孫要素、および自分自身を含みます。したがって、親要素が子要素を含んでいるか、祖先要素が子孫要素を含んでいるかを確認できます。一方で、兄弟要素や、引数にnullを渡した場合はfalseが返されます。子要素が親要素を含むことはありません。この機能は、HTMLのDOM構造を正確に把握し、要素間の関係性をプログラムで効率的にチェックするために非常に役立ちます。

このサンプルコードはPHP 8.2以降で導入された新しいDOM APIを利用しており、それ以前のPHPバージョンでは正常に動作しませんのでご注意ください。querySelector()などのメソッドでHTML要素を取得する際は、要素が見つからない場合にnullが返される可能性があるため、取得した要素が期待通りのオブジェクトであるかを必ず確認してください。contains()メソッドは、対象の要素が引数で指定された要素を、自身を含む形で実際にDOMツリー内に含んでいる場合にtrueを返します。自身やその子孫要素を含んでいる場合はtrueですが、兄弟要素や子要素が親要素に含まれるといった逆の関係ではfalseとなります。引数にnullが渡された場合もfalseを返します。サンプルコード中のloadHTML()のエラー抑制はデモンストレーションのためであり、実際のシステム開発ではエラーハンドリングを適切に行い、問題の早期発見に努めることが重要です。

関連コンテンツ

関連IT用語

関連プログラミング言語

【PHP8.x】Dom\HTMLElement::contains()メソッドの使い方 | いっしー@Webエンジニア