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

Copy
1<?php
2
3/**
4 * DOMNode::contains メソッドの使用例
5 * システムエンジニアを目指す初心者向けに、DOMツリーにおけるノードの包含関係をチェックする方法を解説します。
6 *
7 * DOMNode::contains は、あるDOMノードが別のDOMノードを子孫として含むかどうかを判定します。
8 * これは、PHPの配列が特定の要素を含むかをチェックする in_array() 関数とは異なる点に注意してください。
9 */
10function demonstrateDomContains(): void
11{
12    // 1. DOMDocument オブジェクトを作成します。
13    //    これはHTMLやXMLドキュメント全体を表すコンテナです。
14    $dom = new DOMDocument('1.0', 'UTF-8');
15    $dom->formatOutput = true; // 出力されるXML/HTMLを整形するために設定
16
17    // 2. ルート要素 'div' を作成し、ドキュメントに追加します。
18    //    これにより、DOMツリーの最初の階層が構築されます。
19    $rootElement = $dom->createElement('div');
20    $dom->appendChild($rootElement);
21
22    // 3. 子要素 'span' を作成し、'div' (rootElement) に追加します。
23    //    'span' は 'div' の直接の子ノードです。
24    $childElement = $dom->createElement('span');
25    $rootElement->appendChild($childElement);
26
27    // 4. さらにその子要素 'b' を作成し、'span' (childElement) に追加します。
28    //    'b' は 'span' の直接の子ノードであり、'div' (rootElement) の子孫ノードです。
29    $grandchildElement = $dom->createElement('b');
30    $childElement->appendChild($grandchildElement);
31
32    echo "--- DOMNode::contains の使用例 ---" . PHP_EOL;
33    echo "構築したDOMツリーの概念的な構造:" . PHP_EOL;
34    echo "<div>" . PHP_EOL;
35    echo "  <span>" . PHP_EOL;
36    echo "    <b></b>" . PHP_EOL;
37    echo "  </span>" . PHP_EOL;
38    echo "</div>" . PHP_EOL . PHP_EOL;
39
40    // contains メソッドの様々なケースをテストし、結果を出力します。
41
42    // ケース1: 親ノードが直接の子ノードを含むか？
43    echo "rootElement (div) が childElement (span) を含みますか？ ";
44    var_dump($rootElement->contains($childElement)); // 結果: bool(true) - 'div' は 'span' を含みます。
45
46    // ケース2: 祖先ノードが子孫ノードを含むか？
47    echo "rootElement (div) が grandchildElement (b) を含みますか？ ";
48    var_dump($rootElement->contains($grandchildElement)); // 結果: bool(true) - 'div' は 'b' を含みます（子孫として）。
49
50    // ケース3: 子ノードが親ノードを含むか（逆方向）？
51    echo "childElement (span) が rootElement (div) を含みますか？ ";
52    var_dump($childElement->contains($rootElement)); // 結果: bool(false) - 'span' は 'div' を含みません。
53
54    // ケース4: 同じノード自身を含むか？
55    echo "rootElement (div) が rootElement (div) 自身を含みますか？ ";
56    var_dump($rootElement->contains($rootElement)); // 結果: bool(true) - ノードは自分自身を含みます。
57
58    // ケース5: DOMツリーに属していない無関係なノードを含むか？
59    //         'p' 要素は作成しましたが、ドキュメントに追加していません。
60    $unrelatedElement = $dom->createElement('p');
61    echo "rootElement (div) が unrelatedElement (p) を含みますか？ ";
62    var_dump($rootElement->contains($unrelatedElement)); // 結果: bool(false) - ドキュメント内の関係がないため。
63
64    echo PHP_EOL;
65    echo "補足: DOMNode::contains はDOMツリー内の親子・祖先-子孫関係に基づいた包含をチェックします。" . PHP_EOL;
66    echo "PHPの配列に特定の値があるかを確認するには in_array() 関数を使用するなど、用途が異なります。" . PHP_EOL;
67}
68
69// 上記で定義した関数を実行し、結果を表示します。
70demonstrateDomContains();
71
72?>

DOMNode::containsメソッドは、PHPでHTMLやXMLなどのDOM（Document Object Model）ツリーを扱う際に、あるノードが別のノードを子孫として含んでいるかを判定するために使用されます。このメソッドは、呼び出し元のDOMNodeオブジェクトが、引数として渡された$otherノードを直接の子ノード、またはさらにその子孫ノードとして持っている場合にtrueを返します。そうでない場合はfalseを返します。引数$otherには、比較対象となるDOMNode、DOMNameSpaceNode、またはnullを指定します。

サンプルコードでは、まずDOMDocumentを使ってdiv、span、bという階層構造を持つDOMツリーを構築しています。そして、divノードがspanノードやbノードを含むか、spanノードがdivノードを含むか（逆方向）、自身を含むか、全く関係のないノードを含むかなど、様々なケースでcontainsメソッドの結果を確認しています。例えば、親であるdivが子であるspanや孫であるbを含む場合はtrueとなり、子であるspanが親であるdivを含む場合はfalseとなります。また、ノードは自分自身を含むと判定されます。

このDOMNode::containsは、PHPの配列が特定の要素を持つかを調べるin_array()関数とは異なり、DOMツリーにおけるノードの階層的な包含関係をチェックするメソッドである点にご注意ください。

Copy
1<?php
2
3/**
4 * DOMNode::contains() メソッドの使用例。
5 * あるDOMノードが別のDOMノードを子孫として、または自身として含んでいるかを確認します。
6 * システムエンジニアを目指す初心者向けに、基本的なHTML要素を使って説明します。
7 */
8
9// DOMDocumentオブジェクトを新しく作成します。
10// これはHTMLやXML文書全体を表現するオブジェクトです。
11$dom = new DOMDocument();
12// 出力時にHTMLを整形するように設定します（デバッグや可読性向上に役立ちます）。
13$dom->formatOutput = true;
14
15// 1. ルート要素 'div' を作成します。
16// createElement() はまだドキュメントツリーに追加されていないノードを作成します。
17$divElement = $dom->createElement('div');
18// 作成した 'div' 要素をドキュメントのルートに追加します。
19// これで $divElement はドキュメントツリーの一部となります。
20$dom->appendChild($divElement);
21
22// 2. 子要素 'p' を作成し、'div' の子として追加します。
23$pElement = $dom->createElement('p');
24$divElement->appendChild($pElement); // $divElement の子として $pElement を追加
25
26// 3. 孫要素 'span' を作成し、'p' の子として追加します。
27$spanElement = $dom->createElement('span');
28$pElement->appendChild($spanElement); // $pElement の子として $spanElement を追加
29
30// 4. ドキュメントツリーに追加されていない、無関係な要素 'a' を作成します。
31$aElement = $dom->createElement('a');
32
33echo "--- DOMNode::contains() メソッドの動作確認 ---\n\n";
34
35// ケース1: 親ノードが子ノードを含むか？ (結果: true)
36// $divElement は $pElement を直接の子として含んでいます。
37$result1 = $divElement->contains($pElement);
38echo "div->contains(p): " . ($result1 ? 'true' : 'false') . "\n";
39
40// ケース2: 親ノードが孫ノードを含むか？ (結果: true)
41// $divElement は $pElement を通して $spanElement を子孫として含んでいます。
42$result2 = $divElement->contains($spanElement);
43echo "div->contains(span): " . ($result2 ? 'true' : 'false') . "\n";
44
45// ケース3: 子ノードが親ノードを含むか？ (結果: false)
46// 子ノードは親ノードを含むことはありません。
47$result3 = $pElement->contains($divElement);
48echo "p->contains(div): " . ($result3 ? 'true' : 'false') . "\n";
49
50// ケース4: ノード自身を含むか？ (結果: true)
51// `contains` メソッドは、対象のノード自身も含まれると判断します。
52$result4 = $divElement->contains($divElement);
53echo "div->contains(div): " . ($result4 ? 'true' : 'false') . "\n";
54
55// ケース5: ドキュメントツリーに存在しない、無関係なノードを含むか？ (結果: false)
56// $aElement はどのノードにも追加されていないため、含まれません。
57$result5 = $divElement->contains($aElement);
58echo "div->contains(a): " . ($result5 ? 'true' : 'false') . "\n";
59
60// ケース6: null を渡した場合 (結果: false)
61// `null` は有効なDOMノードではないため、含まれることはありません。
62$result6 = $divElement->contains(null);
63echo "div->contains(null): " . ($result6 ? 'true' : 'false') . "\n";
64
65// 必要に応じて、生成されたHTMLを確認できます。
66// echo "\n--- 生成されたHTML ---\n";
67// echo $dom->saveHTML();
68
69?>

DOMNode::contains() メソッドは、指定されたDOMノードが、別のノードを子孫ノードとして、またはそのノード自身として含んでいるかを確認するためのPHPの機能です。このメソッドはDOMNodeクラスに属し、HTMLやXML文書の要素間の親子関係や包含関係をプログラムで扱う際に利用されます。引数には確認したい対象のノード（DOMNodeまたはDOMNameSpaceNode）かnullを指定し、戻り値として真偽値（bool）を返します。対象のノードを含んでいる場合はtrue、含んでいない場合はfalseとなります。

サンプルコードでは、HTML要素に見立てたdiv、p、spanなどのノードを作成し、それらの包含関係をcontains()で確認しています。例えば、div要素は自身の子要素であるpや、孫要素であるspanを含んでいるためtrueを返します。また、ノード自身についてもtrueを返します。しかし、子要素が親要素を含むことはなく、ドキュメントツリーに属さない無関係なノードやnullを渡した場合はfalseとなります。このメソッドは、ウェブページの特定の要素が別の要素の内部にあるか、あるいは特定のイベントが発生した要素が意図したコンテナ内にあるかなどを判定する際に役立ちます。

Copy
1<?php
2
3/**
4 * 文字列が特定の部分文字列を含むかをチェックするサンプルコードです。
5 * PHP 8で導入されたstr_contains関数を使用します。
6 * これは、提供されたキーワード「php contains substring」に最も関連性の高い機能です。
7 *
8 * @param string $mainString 検索対象の文字列
9 * @param string $subString 検索する部分文字列
10 * @return void
11 */
12function checkStringForSubstring(string $mainString, string $subString): void
13{
14    if (str_contains($mainString, $subString)) {
15        echo "「{$mainString}」は「{$subString}」を含んでいます。\n";
16    } else {
17        echo "「{$mainString}」は「{$subString}」を含んでいません。\n";
18    }
19}
20
21// サンプル使用例
22echo "--- 部分文字列の存在チェック ---\n";
23checkStringForSubstring("Hello, world!", "world");
24checkStringForSubstring("PHP is great.", "PHP");
25checkStringForSubstring("PHP is great.", "php"); // str_containsは大文字小文字を区別します
26checkStringForSubstring("Quick brown fox", "dog");
27
28echo "\n--- 複数のパターンでチェック ---\n";
29$sentence = "エンジニアは毎日コードを書きます。";
30checkStringForSubstring($sentence, "エンジニア");
31checkStringForSubstring($sentence, "コード");
32checkStringForSubstring($sentence, "デザイン");
33
34?>

PHP 8で導入されたstr_contains関数は、文字列が特定の部分文字列を含むかをシンプルにチェックするための機能です。この関数は、第一引数として検索対象となる元の文字列（$mainString）を受け取り、第二引数としてその中に存在するかを確認したい部分文字列（$subString）を受け取ります。

str_contains関数は、部分文字列が元の文字列内で見つかった場合にtrue（真）を返し、見つからなかった場合はfalse（偽）を返します。この戻り値はbool型であり、条件分岐などで簡単に利用できます。重要な点として、str_containsは大文字と小文字を区別して検索します。例えば、「PHP」と「php」は異なる文字列として扱われますので注意が必要です。

サンプルコードでは、checkStringForSubstringという関数を定義し、その中でstr_containsを使って文字列の存在チェックを行っています。$mainStringと$subStringを渡すことで、指定された文字列が部分文字列を含むかどうかが判定され、その結果に応じて適切なメッセージが表示されます。複数のサンプル使用例を通して、str_containsの挙動と、大文字小文字の区別といった特徴を具体的に理解することができます。この機能は、Webアプリケーションにおける入力値の検証やテキスト検索など、多岐にわたる場面で役立ちます。