【PHP8.x】containsメソッドの使い方
containsメソッドの使い方について、初心者にもわかりやすく解説します。
基本的な使い方
containsメソッドは、引数で指定したノードが、そのDocumentオブジェクトの子孫であるかどうかを判定するために実行するメソッドです。このメソッドは、確認したいDOM\Nodeオブジェクトを引数として受け取り、そのノードがドキュメントのDOMツリー内に存在すればtrueを、存在しなければfalseを返します。ここで言う「子孫」とは、直接の子ノードだけでなく、そのさらに下層にある孫ノードなど、ドキュメントに含まれるすべてのノードを指します。また、Documentオブジェクト自身を引数に指定した場合も、そのノードは自身に含まれているとみなされtrueが返ります。一方で、引数で指定したノードがこのドキュメントのDOMツリーに属していない場合や、引数がnullである場合はfalseを返します。このメソッドを利用することで、特定のノードが現在のドキュメントの一部であるかを安全に確認し、意図しないノード操作を防ぐことができます。
構文(syntax)
1<?php 2 3$document = new Dom\Document(); 4$document->loadHTML('<html><body><p>test</p></body></html>'); 5 6// ドキュメント内に存在するノードを取得 7$node = $document->getElementsByTagName('p')->item(0); 8 9// 構文: public function contains(?Dom\Node $other): bool 10$isContained = $document->contains($node); 11 12var_dump($isContained); // bool(true) 13 14?>
引数(parameters)
?Dom\Node $other
- ?Dom\Node $other: 比較対象となるDOMノードを指定します。このノードが現在の
Dom\Documentのツリー内に存在するかどうかを確認します。
戻り値(return)
戻り値なし
戻り値はありません
サンプルコード
PHP配列の特定値存在チェック
1<?php 2 3/** 4 * 指定された値が配列内に存在するかどうかをチェックします。 5 * 6 * この関数は、PHPで配列に特定の要素が含まれているかを確認するための 7 * 一般的な方法である `in_array()` 関数をラップして提供します。 8 * システムエンジニアを目指す初心者の方にも、配列操作の基本として 9 * 理解しやすいように設計されています。 10 * 11 * @param mixed $needle 検索する値 12 * @param array $haystack 検索対象となる配列 13 * @param bool $strict 厳密な型比較を行うかどうか (デフォルトは false) 14 * true の場合、値だけでなく型も一致する必要があります。 15 * false の場合、型が異なっていても値が等しければtrueを返します。 16 * @return bool 値が配列内に存在すれば true、そうでなければ false 17 */ 18function checkArrayContainsValue(mixed $needle, array $haystack, bool $strict = false): bool 19{ 20 // in_array() 関数は、配列 ($haystack) 内に指定された値 ($needle) が 21 // 存在するかどうかをチェックします。 22 // 第3引数 $strict を true に設定すると、値と型が両方とも一致する場合のみ 23 // 存在すると判断します（例: 5 と "5" は厳密には異なる）。 24 return in_array($needle, $haystack, $strict); 25} 26 27// --- サンプルコードの実行例 --- 28 29// 数値の配列 30$numbers = [10, 20, 30, 40, 50]; 31echo "現在の配列: [" . implode(', ', $numbers) . "]\n\n"; 32 33// 値 '30' が配列に含まれているか確認 (非厳密比較) 34if (checkArrayContainsValue(30, $numbers)) { 35 echo "ケース1: 30 は配列に含まれています。\n"; 36} else { 37 echo "ケース1: 30 は配列に含まれていません。\n"; 38} 39 40// 値 '60' が配列に含まれているか確認 41if (checkArrayContainsValue(60, $numbers)) { 42 echo "ケース2: 60 は配列に含まれています。\n"; 43} else { 44 echo "ケース2: 60 は配列に含まれていません。\n"; 45} 46 47// 文字列の配列 48$fruits = ['apple', 'banana', 'cherry']; 49echo "\n現在の配列: [" . implode(', ', $fruits) . "]\n\n"; 50 51// 値 'banana' が配列に含まれているか確認 52if (checkArrayContainsValue('banana', $fruits)) { 53 echo "ケース3: 'banana' は配列に含まれています。\n"; 54} else { 55 echo "ケース3: 'banana' は配列に含まれていません。\n"; 56} 57 58// 厳密な型比較の例 59$mixedArray = [1, '2', 3.0, 'four']; 60echo "\n現在の配列: [" . implode(', ', $mixedArray) . "]\n\n"; 61 62// 非厳密比較: 数値 2 と文字列 '2' は等しいとみなされる 63if (checkArrayContainsValue(2, $mixedArray, false)) { 64 echo "ケース4: 非厳密比較 - 数値 2 は配列に含まれています。\n"; 65} else { 66 echo "ケース4: 非厳密比較 - 数値 2 は配列に含まれていません。\n"; 67} 68 69// 厳密比較: 数値 2 と文字列 '2' は等しくないとみなされる 70if (checkArrayContainsValue(2, $mixedArray, true)) { 71 echo "ケース5: 厳密比較 - 数値 2 は配列に含まれています。\n"; 72} else { 73 echo "ケース5: 厳密比較 - 数値 2 は配列に含まれていません。\n"; 74} 75 76// 厳密比較: 浮動小数点数 3.0 と整数 3 は等しくないとみなされる 77if (checkArrayContainsValue(3, $mixedArray, true)) { 78 echo "ケース6: 厳密比較 - 整数 3 は配列に含まれています。\n"; 79} else { 80 echo "ケース6: 厳密比較 - 整数 3 は配列に含まれていません。\n"; 81} 82?>
PHPのDom\Document::containsメソッドは、主にDOM（Document Object Model）ツリーにおけるノードの親子関係を確認するために用いられますが、ご提示のサンプルコードとキーワードは、PHPで配列の中に特定の値が含まれているかを確認する一般的な方法を示しています。このサンプルコードは、システムエンジニアを目指す初心者の方にも分かりやすく配列操作の基本を学べるよう設計されています。
サンプルコードで定義されているcheckArrayContainsValue関数は、配列内に指定された値が存在するかどうかをチェックします。この関数は、PHPに標準で備わっているin_array()関数を内部で利用しています。
引数について、$needleは配列の中から検索したい値を、$haystackは検索対象となる配列を指定します。$strict引数はオプションで、検索時の比較方法を決定します。trueに設定すると、値だけでなくデータの型も完全に一致する場合にのみ「含まれる」と判断します。例えば、数値の5と文字列の"5"は、$strictがtrueの場合は異なるものとして扱われます。一方、false（デフォルト）の場合は値が等しければ型が異なっていても一致するとみなされます。
この関数は、値が配列内に見つかればtrueを、見つからなければfalseを戻り値として返します。システム開発において、データの存在確認は頻繁に行われる操作であり、このin_array()関数の使い方を理解することは、PHPでのプログラミングの基礎となります。
提供されたリファレンスの Dom\Document::contains は、HTML/XML文書内のDOM要素の包含関係を調べるメソッドであり、配列の要素検索には利用できません。初心者はこの点を混同しないよう注意が必要です。
サンプルコードで示されている in_array() 関数こそが、PHPで配列に特定の値が存在するかを判定するための正しい方法です。この関数の第3引数 $strict は特に重要で、true に設定すると値だけでなくデータ型も厳密に一致する場合のみ true を返します。型の違いによる意図しない結果を防ぐため、厳密な比較が必要な場合は必ず $strict を true に設定してください。
PHP Dom\Document::contains() でノード包含を判定する
1<?php 2 3/** 4 * Dom\Document (および Dom\Node) の contains() メソッドの使用例を示します。 5 * 6 * contains() メソッドは、あるノードが別のノードの子孫であるかどうかを判定します。 7 * Dom\Document クラスは Dom\Node を継承しているため、このメソッドを呼び出すことができます。 8 * PHP 8 以降で利用可能です。 9 */ 10function demonstrateDomDocumentContains(): void 11{ 12 // 1. Dom\Document オブジェクトを作成し、HTMLコンテンツを読み込みます。 13 $document = new Dom\Document(); 14 // HTMLコンテンツ。包含関係を示すために複数の要素を含めます。 15 $htmlContent = <<<HTML 16 <div id="container"> 17 <p id="paragraph">これは段落です。</p> 18 <ul> 19 <li id="item1">リストアイテム1</li> 20 <li id="item2">リストアイテム2</li> 21 </ul> 22 </div> 23 <span id="external">これはコンテナの外にある要素です。</span> 24 HTML; 25 $document->loadHTML($htmlContent); 26 27 // DomXPath を使用して、テスト対象のノードを効率的に取得します。 28 // XPathは、HTML/XMLドキュメント内の要素を選択するための強力な言語です。 29 $xpath = new Dom\XPath($document); 30 31 // 2. 比較対象となるノードを取得します。 32 // item(0) は、クエリ結果の最初の要素を取得します。 33 $containerNode = $xpath->query('//*[@id="container"]')->item(0); 34 $paragraphNode = $xpath->query('//*[@id="paragraph"]')->item(0); 35 $item1Node = $xpath->query('//*[@id="item1"]')->item(0); 36 $externalNode = $xpath->query('//*[@id="external"]')->item(0); 37 38 echo "--- Dom\\Document/Dom\\Node の contains() メソッド使用例 ---\n\n"; 39 40 // 3. contains() メソッドを使ってノードの包含関係をチェックし、結果を表示します。 41 42 // 例1: Dom\Document が自身の子孫ノードを含むか 43 // Dom\Document はDOMツリーのルートであり、その中にある全てのノードは子孫と見なされます。 44 $result1 = $document->contains($containerNode); 45 echo "Document が '#container' ノードを含みますか？ " . ($result1 ? "はい" : "いいえ") . " (期待値: はい)\n"; 46 47 // 例2: 親ノードが直接の子ノードを含むか 48 // '#container' は '#paragraph' を直接の子として含みます。 49 if ($containerNode && $paragraphNode) { 50 $result2 = $containerNode->contains($paragraphNode); 51 echo "'#container' が '#paragraph' ノードを含みますか？ " . ($result2 ? "はい" : "いいえ") . " (期待値: はい)\n"; 52 } 53 54 // 例3: 親ノードが孫ノードを含むか 55 // '#container' は 'ul' を経由して '#item1' を孫として含みます。 56 if ($containerNode && $item1Node) { 57 $result3 = $containerNode->contains($item1Node); 58 echo "'#container' が '#item1' ノードを含みますか？ " . ($result3 ? "はい" : "いいえ") . " (期待値: はい)\n"; 59 } 60 61 // 例4: 子ノードが親ノードを含むか（逆の関係） 62 // '#paragraph' は '#container' を含みません。 63 if ($paragraphNode && $containerNode) { 64 $result4 = $paragraphNode->contains($containerNode); 65 echo "'#paragraph' が '#container' ノードを含みますか？ " . ($result4 ? "はい" : "いいえ") . " (期待値: いいえ)\n"; 66 } 67 68 // 例5: 互いに含まない兄弟関係や異なるツリーのノード 69 // '#container' と '#external' は同じレベルの兄弟関係にあり、互いに含みません。 70 if ($containerNode && $externalNode) { 71 $result5 = $containerNode->contains($externalNode); 72 echo "'#container' が '#external' ノードを含みますか？ " . ($result5 ? "はい" : "いいえ") . " (期待値: いいえ)\n"; 73 } 74 75 // 例6: ノードが自分自身を含むか 76 // contains() メソッドは、ノードが自分自身を含むと見なします。 77 if ($containerNode) { 78 $result6 = $containerNode->contains($containerNode); 79 echo "'#container' ノードが自分自身を含みますか？ " . ($result6 ? "はい" : "いいえ") . " (期待値: はい)\n"; 80 } 81 82 // 例7: null を引数に渡した場合 83 // null はどのノードの子孫でもないため、常に false を返します。 84 if ($containerNode) { 85 $result7 = $containerNode->contains(null); 86 echo "'#container' ノードが null を含みますか？ " . ($result7 ? "はい" : "いいえ") . " (期待値: いいえ)\n"; 87 } 88} 89 90// 定義した関数を実行して、Dom\Document::contains() の動作を確認します。 91demonstrateDomDocumentContains();
このPHPサンプルコードは、Dom\Documentクラス（およびその親であるDom\Nodeクラス）が提供するcontains()メソッドの使い方を実演しています。PHP 8以降で利用可能なこのメソッドは、あるDOMノードが、別の指定されたノードをその子孫として含んでいるかどうかを判定するために使用されます。
contains()メソッドは引数として?Dom\Node $otherを取り、これが現在のノードの子孫であるかを調べます。戻り値は真偽値（bool）で、含まれていればtrueを、含まれていなければfalseを返します。ただし、現在のノード自身は子孫として含まれると見なされ、引数にnullを渡した場合は常にfalseが返されます。
サンプルコードでは、まずHTMLコンテンツからDom\Documentオブジェクトを生成し、Dom\XPathを使って特定のノード（例：#container、#paragraph、#item1、#external）を取得しています。その後、これらのノード間の様々な包含関係についてcontains()メソッドを呼び出し、その結果を表示しています。例えば、親要素が子要素や孫要素を含む場合はtrueとなり、逆に子要素が親要素を含む場合はfalseとなります。また、互いに異なるツリーに存在するノードや、ノード自身を引数とした場合の挙動も確認できます。これにより、contains()メソッドがDOMツリー内でのノードの親子関係や祖先・子孫関係をどのように評価するかが具体的に理解できます。
このメソッドは、呼び出し元のノードが引数で指定されたノード自身、またはその子孫ノードを含んでいるかを判定し、その結果を真偽値（trueまたはfalse）で返します。提供されたリファレンス情報では「戻り値なし」とありますが、これは誤りであり、実際にはbool型の戻り値がある点に注意が必要です。Dom\DocumentクラスはDom\Nodeを継承しているため、このcontainsメソッドを呼び出せます。引数にnullを渡した場合は常にfalseとなります。ノードが自分自身を含む場合はtrueですが、親子関係が逆転する場合や、異なるDOMツリーに属するノードなど、包含関係にない場合はfalseとなります。この機能はPHP 8以降で利用可能です。