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

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

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

作成日: 更新日:

基本的な使い方

『containsメソッドは、あるノードがこのエンティティノードの子孫であるかどうかを判定するために実行するメソッドです。引数には、判定したいDom\Nodeオブジェクト、またはnullを渡します。メソッドを呼び出したエンティティノード自身、またはその子や孫といった子孫ノードを引数に指定した場合、このメソッドはtrueを返します。一方で、引数で指定したノードが子孫ではない場合や、引数がnullであった場合にはfalseを返します。このメソッドは、Dom\Entityクラスが親クラスであるDom\Nodeから継承した機能であり、XMLやHTML文書が持つ階層的な木構造（DOMツリー）における、ノード間の包含関係を調べるために使用されます。文書構造をプログラムで解析する際に、特定の要素がこのエンティティの内部に存在するかどうかを効率的に確認したい場合に役立ちます。戻り値は真偽値であるため、if文などの条件分岐で利用するのが一般的です。』

構文(syntax)

1<?php
2
3// public function Dom\Entity::contains(?Dom\Node $other): bool
4
5// DTDを含むXMLドキュメントを準備します
6$xml = <<<XML
7<?xml version="1.0" encoding="UTF-8"?>
8<!DOCTYPE root [
9    <!ENTITY myEntity "entity text node">
10]>
11<root />
12XML;
13
14$doc = new DOM\Document();
15$doc->loadXML($xml);
16
17// 'myEntity' という名前の Dom\Entity ノードを取得します
18$entityNode = $doc->doctype->entities->getNamedItem('myEntity');
19
20// $entityNode の子ノードを取得します (この場合はテキストノード)
21$childNode = $entityNode->firstChild;
22
23// 別のノード（ドキュメントのルート要素）を取得します
24$anotherNode = $doc->documentElement;
25
26// $entityNode が $childNode を子孫として含んでいるか確認します
27$isContained = $entityNode->contains($childNode);
28
29// $entityNode が $anotherNode を子孫として含んでいるか確認します
30$isNotContained = $entityNode->contains($anotherNode);
31
32?>

引数(parameters)

?Dom\Node $other

  • ?Dom\Node $other: 比較対象となるDOMノード

戻り値(return)

bool

このメソッドは、指定された要素が現在の DOM エンティティ内に含まれているかどうかを示すブール値 (true または false) を返します。

サンプルコード

PHP Dom\Node::containsでノード包含を判定する

1<?php
2
3declare(strict_types=1);
4
5/**
6 * Dom\Node::contains の使用例を示します。
7 *
8 * このメソッドは、あるDOMノードが別のノードを子孫として内包しているかを判定します。
9 * HTMLドキュメントの親子関係を調べるためのものであり、
10 * 配列内に特定の値が存在するかを調べる in_array() 関数とは目的が異なります。
11 */
12function checkDomNodeContainment(): void
13{
14    // 解析対象のシンプルなHTML文字列を準備
15    $html = <<<HTML
16    <!DOCTYPE html>
17    <html>
18    <body>
19        <div id="parent">
20            <p id="child">
21                <span id="grandchild">テキスト</span>
22            </p>
23        </div>
24        <div id="uncle"></div>
25    </body>
26    </html>
27    HTML;
28
29    // DOMDocumentオブジェクトを生成し、HTMLを読み込む
30    $doc = new DOMDocument();
31    // HTML5の要素で警告が出ないようにエラーハンドリングを内部で行う
32    libxml_use_internal_errors(true);
33    $doc->loadHTML($html);
34    libxml_clear_errors();
35
36    // ID属性から各要素ノードを取得
37    $parent = $doc->getElementById('parent'); // div#parent
38    $child = $doc->getElementById('child');   // p#child
39    $grandchild = $doc->getElementById('grandchild'); // span#grandchild
40    $uncle = $doc->getElementById('uncle');   // div#uncle
41
42    // --- containsメソッドによる包含関係のチェック ---
43
44    // 例1: 親ノードが孫ノードを含んでいるか (true)
45    // #parent は #grandchild を子孫として内包しています。
46    $result1 = $parent->contains($grandchild);
47    echo '親は孫を含んでいるか？: ';
48    var_dump($result1); // bool(true)
49
50    // 例2: 子ノードが親ノードを含んでいるか (false)
51    // #child は #parent の子孫であり、その逆ではありません。
52    $result2 = $child->contains($parent);
53    echo '子は親を含んでいるか？: ';
54    var_dump($result2); // bool(false)
55
56    // 例3: 親ノードが兄弟関係のノードを含んでいるか (false)
57    // #parent と #uncle は親子関係にありません。
58    $result3 = $parent->contains($uncle);
59    echo '親は叔父を含んでいるか？: ';
60    var_dump($result3); // bool(false)
61
62    // 例4: ノード自身を含んでいるか (true)
63    // containsは引数に自身を渡すとtrueを返します。
64    $result4 = $parent->contains($parent);
65    echo '親は親自身を含んでいるか？: ';
66    var_dump($result4); // bool(true)
67
68    // 例5: 引数に null を渡した場合 (false)
69    // 引数は ?Dom\Node であり、null許容ですが、nullの場合はfalseを返します。
70    $result5 = $parent->contains(null);
71    echo '親はnullを含んでいるか？: ';
72    var_dump($result5); // bool(false)
73}
74
75// 関数を実行して結果を表示
76checkDomNodeContainment();

このPHPコードは、Dom\Entity::containsメソッドの使用方法を示しています。このメソッドは、HTMLやXMLのような階層構造を持つドキュメント（DOMツリー）において、あるノードが指定した別のノードを子孫として含んでいるかどうかを判定するために使用します。配列に特定の値が含まれるか調べるin_array()関数とは目的が異なります。

containsメソッドは、引数に判定対象となるDom\Nodeオブジェクトを受け取ります。呼び出し元のノードが引数のノードを子孫として内包していればtrue、そうでなければfalseという真偽値を返します。引数にはnullを渡すこともでき、その場合はfalseが返されます。

サンプルコードでは、まずHTML文字列を解析し、「親(parent)」「子(child)」「孫(grandchild)」「叔父(uncle)」というIDを持つ各要素を取得しています。

$parent->contains($grandchild)の結果は、parent要素がgrandchild要素を子孫として含んでいるためtrueになります。逆に、親子関係が逆の$child->contains($parent)や、兄弟関係である$parent->contains($uncle)はfalseです。また、$parent->contains($parent)のように自分自身を引数に指定した場合はtrueを返す仕様です。このように、containsメソッドはドキュメント内の要素間の親子関係を正確に調べる際に役立ちます。

Dom\Entity::containsメソッドは、HTMLやXMLドキュメントの親子・子孫関係を調べるための専用の機能です。配列内に特定の値があるかを探すin_array()関数や、文字列が含まれているかを調べるstr_contains()関数とは目的が全く異なるため、混同しないように注意が必要です。このメソッドにおける「含む」とは、ある要素が指定された要素を直接の子だけでなく、孫やひ孫として内包している状態を指します。また、自分自身のノードを引数に渡した場合はtrueを返します。引数にnullを渡してもエラーにはならず、安全にfalseが返されるため、ノードの取得に失敗した場合でも安心して使用できます。

PHP Dom\Node::contains で要素の包含関係を判定する

1<?php
2
3declare(strict_types=1);
4
5/**
6 * Dom\Node::contains の動作を確認するサンプルコード
7 *
8 * この関数は、指定したHTMLドキュメント内で、
9 * ある要素が他の要素を子孫として含んでいるかどうかを判定します。
10 * Dom\Entity は Dom\Node を継承しているため、このメソッドを利用できますが、
11 * より一般的な例として Dom\Element を使用します。
12 */
13function checkNodeContainment(): void
14{
15    // HTML文字列を定義
16    $html = <<<HTML
17<!DOCTYPE html>
18<html>
19<body>
20    <div id="parentElement">
21        <p id="childElement">これは子要素です。</p>
22    </div>
23    <span id="outsideElement">これは外部の要素です。</span>
24</body>
25</html>
26HTML;
27
28    // DOMDocumentオブジェクトを作成し、HTMLを読み込む
29    $dom = new DOMDocument();
30    // HTML5のタグに対する警告を抑制しつつ読み込み
31    @$dom->loadHTML($html, LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD);
32
33    // ID属性を元に各DOMNode (DOMElement) を取得
34    $parent = $dom->getElementById('parentElement');
35    $child = $dom->getElementById('childElement');
36    $outside = $dom->getElementById('outsideElement');
37
38    // 親要素がnullでないことを確認
39    if ($parent === null || $child === null || $outside === null) {
40        echo '要素の取得に失敗しました。' . PHP_EOL;
41        return;
42    }
43
44    // --- Dom\Node::contains の使用例 ---
45    // 指定したノードが子孫であるか（または自身であるか）を判定します。
46
47    // 1. 親要素が子要素を含んでいるかチェック (trueになる)
48    $isChildContained = $parent->contains($child);
49    var_dump($isChildContained); // 出力: bool(true)
50
51    // 2. 親要素が外部の要素を含んでいるかチェック (falseになる)
52    $isOutsideContained = $parent->contains($outside);
53    var_dump($isOutsideContained); // 出力: bool(false)
54
55    // 3. 親要素が自身を含んでいるかチェック (trueになる)
56    $isSelfContained = $parent->contains($parent);
57    var_dump($isSelfContained); // 出力: bool(true)
58    
59    // 4. 引数に null を渡した場合 (falseになる)
60    $isNullContained = $parent->contains(null);
61    var_dump($isNullContained); // 出力: bool(false)
62}
63
64// 関数を実行
65checkNodeContainment();

Dom\Node::contains()メソッドは、あるHTML要素（ノード）が、引数で指定した別の要素を子孫として含んでいるかどうかを判定するために使用します。HTMLドキュメントの親子関係や階層構造をプログラムで確認する際に役立ちます。

このメソッドの引数には、含まれているか調べたい対象のノードオブジェクトを指定します。nullを渡すことも可能です。戻り値は真偽値（bool型）であり、trueまたはfalseのいずれかが返されます。

メソッドを呼び出したノードが、引数で指定したノードを子孫として内包している場合、または引数のノードが自分自身である場合にtrueを返します。サンプルコードの例では、parentElementがchildElementを含んでいるためtrueとなります。一方、親子関係にないoutsideElementや、引数にnullを渡した場合はfalseを返します。このように、特定の要素が他の要素の範囲内に存在するかどうかを簡単にチェックできます。

Dom\Node::containsメソッドは、ある要素が指定した要素を子孫として含んでいるかだけでなく、自分自身であるかも判定します。そのため、サンプルコードのように同じ要素を渡すとtrueが返る点に注意が必要です。この親子関係は、HTMLを解析して作られたDOMツリーの階層構造に基づいて決まります。また、引数にはnullを渡すことができ、その場合はエラーにならず安全にfalseを返します。getElementByIdなどで取得した要素がnullの可能性がある場合でも、プログラムが停止する心配はありません。このメソッドは、DOMElementだけでなく、Dom\Nodeを継承するすべてのノードで利用できます。

関連コンテンツ

関連IT用語

関連プログラミング言語