【PHP8.x】containsメソッドの使い方
containsメソッドの使い方について、初心者にもわかりやすく解説します。
基本的な使い方
containsメソッドは、PHPのDOMAttrクラスに属するメソッドで、特定のHTMLやXML要素の属性値が、指定された文字列（トークン）を含むかどうかを判定するメソッドです。
DOMAttrクラスは、ウェブページなどのドキュメントを構成する要素の「属性」を表現するためのオブジェクトです。例えば、<div class="example active">というHTML要素がある場合、class="example active"という部分全体がDOMAttrオブジェクトとして扱われます。このcontainsメソッドは、特にclass属性のように、複数の値をスペースで区切って記述する属性値（これをDOMTokenListと呼びます）に対して非常に効果を発揮します。メソッドが実行されると、属性値を空白で区切って複数の文字列（トークン）に分解し、その中から引数として渡された文字列と完全に一致するものがあるかどうかを効率的に探索します。
このメソッドを使用することで、例えば、ある要素が特定のCSSクラス（例: activeクラス）を持っているかどうかを、簡単かつ明確に確認することができます。属性値を手動で解析したり、複雑な正規表現を使用したりする手間を省き、より安全で保守しやすいコードを記述できます。指定されたトークンが属性値のリストに含まれている場合はtrueを、含まれていない場合はfalseを返します。ウェブアプリケーションで要素の状態を動的に判別したり、表示を切り替えたりする際に、DOM操作を簡潔に進めるための便利な機能です。
構文(syntax)
1<?php 2 3// DOMドキュメントを作成し、HTMLを読み込む 4$doc = new DOMDocument(); 5$doc->loadHTML('<p id="greeting">Hello</p>'); 6 7// p要素から id属性ノード (DOMAttr) を取得 8$attrNode = $doc->getElementsByTagName('p')->item(0)->getAttributeNode('id'); 9 10// 属性ノードが持つ子ノード (この場合はテキストノード "greeting") を取得 11$textNode = $attrNode->firstChild; 12 13/* 14 * public DOMNode::contains(?DOMNode $other): bool 15 * 16 * $other で指定したノードが、このノードの子孫であるかどうかを調べます。 17 * DOMAttr は DOMNode を継承しているため、このメソッドを使用できます。 18 */ 19$result = $attrNode->contains($textNode); 20 21// 結果は true になります 22var_dump($result); 23 24?>
引数(parameters)
DOMNode $other
- DOMNode $other: 比較対象となる
DOMNodeオブジェクト
戻り値(return)
戻り値なし
戻り値はありません
サンプルコード
PHP DOMAttr::contains() で子ノードを含むか判定する
1<?php 2 3/** 4 * DOMAttr::contains() メソッドの動作をデモンストレーションする関数。 5 * 6 * この関数は、HTML文字列からDOMドキュメントを生成し、 7 * 特定の要素の属性ノードが、その子ノード（通常はテキストノード）や 8 * その他のノードを含んでいるかを contains() メソッドを使って確認します。 9 * 10 * DOMAttr::contains() は、属性ノードが引数で指定されたノードを 11 * 子孫として持っている場合に true を返します。 12 * 属性ノードは通常、その値に対応する単一のテキストノードを子として持ちます。 13 */ 14function demonstrateDomAttrContains(): void 15{ 16 // 1. DOMDocument オブジェクトを作成し、HTML文字列をロードします。 17 // '@' は loadHTML() が生成する警告を抑制するための一時的な措置です。 18 // 実際のアプリケーションでは適切なエラーハンドリングを行うべきです。 19 $dom = new DOMDocument(); 20 $html = '<div id="myDiv">Hello, World!</div>'; 21 @$dom->loadHTML($html); 22 23 // 2. HTMLドキュメントから最初の 'div' 要素を取得します。 24 $divElement = $dom->getElementsByTagName('div')->item(0); 25 26 // 要素が正常に取得できたかを確認します。 27 if ($divElement instanceof DOMElement) { 28 // 3. 'div' 要素から 'id' 属性 (DOMAttr オブジェクト) を取得します。 29 $idAttr = $divElement->getAttributeNode('id'); 30 31 // 属性が正常に取得できたかを確認します。 32 if ($idAttr instanceof DOMAttr) { 33 echo "--- DOMAttr::contains() のデモンストレーション ---\n\n"; 34 echo "取得した属性ノード名: " . $idAttr->nodeName . "\n"; // 例: id 35 echo "取得した属性ノード値: " . $idAttr->nodeValue . "\n"; // 例: myDiv 36 37 // DOMAttr は通常、その属性値を表す DOMText ノードを唯一の子として持ちます。 38 $attrTextNode = $idAttr->firstChild; 39 40 // 属性の子ノードがテキストノードであることを確認します。 41 if ($attrTextNode instanceof DOMText) { 42 echo "\n属性ノードの子ノード (DOMText) の値: " . $attrTextNode->nodeValue . "\n"; 43 echo "属性ノードの子ノード (DOMText) の型: " . get_class($attrTextNode) . "\n\n"; 44 45 // 4. DOMAttr::contains() を使用して、属性ノードが自身の子ノードを 46 // 含んでいるかを確認します。これは通常 true を返します。 47 $containsChildText = $idAttr->contains($attrTextNode); 48 echo "DOMAttr::contains(\$attrTextNode): " . ($containsChildText ? 'true' : 'false') . "\n"; 49 echo " (属性ノードはその値（テキストノード）を子孫として含んでいます)\n\n"; 50 51 // 別のノード（例: documentの<body>要素）が属性ノードに含まれるかを確認します。 52 // 属性ノードが要素ノードを子孫として含むことは通常ありません。 53 $bodyNode = $dom->getElementsByTagName('body')->item(0); 54 if ($bodyNode instanceof DOMNode) { 55 $containsBodyNode = $idAttr->contains($bodyNode); 56 echo "DOMAttr::contains(\$bodyNode): " . ($containsBodyNode ? 'true' : 'false') . "\n"; 57 echo " (属性ノードは通常、HTMLドキュメントの<body>要素を子孫として含みません)\n"; 58 } 59 } else { 60 echo "警告: 'id' 属性の子ノードが DOMText ではありませんでした。\n"; 61 } 62 } else { 63 echo "警告: 'id' 属性が見つかりませんでした。\n"; 64 } 65 } else { 66 echo "警告: 'div' 要素が見つかりませんでした。\n"; 67 } 68} 69 70// 関数を実行してデモンストレーションを開始します。 71demonstrateDomAttrContains();
PHP 8のDOMAttr::contains()メソッドは、XMLやHTMLドキュメントの構造を扱うDOMAttrクラスに属し、特定の属性ノードが別のノードを子孫として含んでいるかを確認するために使用されます。
このメソッドはDOMNode $otherという引数を受け取ります。これは、属性ノードが子孫として含んでいるかを確認したい対象のノードを指定するものです。DOMAttrは通常、その属性値を表現するDOMTextノードを唯一の子として持ちます。
戻り値はbool型で、属性ノードが引数で指定されたノードを子孫として持っている場合はtrueを、そうでない場合はfalseを返します。例えば、id="myDiv"という属性ノードがあった場合、その属性値である「myDiv」を表すテキストノードをcontains()の引数に渡すとtrueが返されます。一方、ドキュメント内の別の<div>要素ノードなどを引数に渡しても、属性ノードは通常それらを子孫として持たないため、falseが返されることになります。この機能は、DOMツリー内のノードの親子関係をプログラムで確認する際に役立ちます。
提供されたリファレンス情報では、DOMAttr::contains()メソッドは戻り値を返さないとされていますが、サンプルコードでは真偽値が返されるかのように利用されています。この違いにより、コードが意図通りに動作しない可能性がありますのでご注意ください。PHPのDOM拡張ではXMLやHTMLの構造を厳密に扱うため、DOMツリーの親子関係やノードの種類をよく理解することが重要です。また、サンプルコードにある@演算子によるエラー抑制は、問題を見逃す原因となるため、実際のシステムでは適切なエラーハンドリングを行うようにしましょう。このcontainsメソッドはDOMノード間の親子関係を調べるものであり、配列の要素検索とは機能が異なりますので混同しないよう注意してください。
PHP DOMAttr::contains() で要素包含をチェックする
1<?php 2 3/** 4 * DOMAttr::contains() メソッドのサンプルコード 5 * 6 * このメソッドは、DOMAttrが属する要素 (owner element) が、 7 * 指定されたDOMNodeを子孫として含んでいるか、または指定されたDOMNodeがowner element自身であるかをチェックします。 8 * PHP 8 で導入されました。 9 * 10 * 【注記】提供されたリファレンス情報では「戻り値: 戻り値なし」とありましたが、 11 * PHP 8 の実際の DOMAttr::contains() メソッドは真偽値 (bool) を返します。 12 * このサンプルコードでは、初心者の方にも分かりやすいよう、実際の戻り値に基づき動作を示します。 13 */ 14 15// 1. DOMDocument を作成し、HTMLコンテンツを読み込む 16$dom = new DOMDocument(); 17// HTMLをパースして、ID 'parent' を持つdiv要素と、その中に属性 'data-info' を含むサンプルを作成 18$dom->loadHTML('<div id="parent" data-info="example-value"><p>First child paragraph</p><span>Second child span</span></div>'); 19 20// 2. 属性のowner element (親要素) を取得する 21$parentElement = $dom->getElementById('parent'); 22 23if (!$parentElement) { 24 echo "エラー: 'parent' IDを持つ要素が見つかりません。\n"; 25 exit(1); 26} 27 28// 3. DOMAttr インスタンスを取得する 29// 今回は 'data-info' という属性を取得します。 30$domAttr = $parentElement->attributes->getNamedItem('data-info'); 31 32if (!$domAttr) { 33 echo "エラー: 'data-info' 属性が見つかりません。\n"; 34 exit(1); 35} 36 37echo "DOMAttr (属性名: '{$domAttr->name}', owner element: '{$parentElement->tagName}#{$parentElement->id}') の contains() メソッドのデモンストレーション:\n\n"; 38 39// 4. 比較対象となるDOMNodeインスタンスを取得する 40// 属性のowner element ($parentElement) の子孫であるノード 41$childParagraph = $parentElement->getElementsByTagName('p')->item(0); 42$childSpan = $parentElement->getElementsByTagName('span')->item(0); 43 44// 文書内に存在するが、owner elementの子孫ではないノード (例: body要素) 45$bodyElement = $dom->getElementsByTagName('body')->item(0); 46 47// 文書内に存在しない新しいノード 48$newNode = $dom->createElement('a'); 49 50// 5. DOMAttr::contains() メソッドを使用し、DOMNodeが含まれているか確認する 51// contains() は owner element を基準にチェックします。 52 53// owner elementの子孫であるDOMNodeを渡した場合 54if ($childParagraph) { 55 $result1 = $domAttr->contains($childParagraph); 56 echo " - owner elementが 'p' 要素 (First child) を含みますか？: " . ($result1 ? "はい" : "いいえ") . "\n"; // 期待値: はい 57} 58 59if ($childSpan) { 60 $result2 = $domAttr->contains($childSpan); 61 echo " - owner elementが 'span' 要素 (Second child) を含みますか？: " . ($result2 ? "はい" : "いいえ") . "\n"; // 期待値: はい 62} 63 64// owner element自身を渡した場合 65$result3 = $domAttr->contains($parentElement); 66echo " - owner elementが owner element自身を含みますか？: " . ($result3 ? "はい" : "いいえ") . "\n"; // 期待値: はい (contains() の定義により) 67 68// owner elementの子孫ではないDOMNodeを渡した場合 69if ($bodyElement) { 70 $result4 = $domAttr->contains($bodyElement); 71 echo " - owner elementが 'body' 要素を含みますか？: " . ($result4 ? "はい" : "いいえ") . "\n"; // 期待値: いいえ 72} 73 74// 文書内に存在しないノードを渡した場合 75$result5 = $domAttr->contains($newNode); 76echo " - owner elementが新しい 'a' 要素 (文書外) を含みますか？: " . ($result5 ? "はい" : "いいえ") . "\n"; // 期待値: いいえ 77 78?>
DOMAttr::contains()はPHP 8で導入されたメソッドで、DOMAttrインスタンスが属する要素（これを「オーナー要素」と呼びます）が、引数として渡されたDOMNodeを子孫として含んでいるか、または指定されたDOMNodeがオーナー要素自身であるかを検査します。
このメソッドの引数には、チェックしたいDOMNodeインスタンスを指定します。戻り値は真偽値（bool）で、オーナー要素が指定されたDOMNodeを含んでいる、あるいは指定されたDOMNodeがオーナー要素自身である場合にtrueを、そうでない場合にfalseを返します。
サンプルコードでは、IDが「parent」のdiv要素に紐づくDOMAttrを例に挙げています。このDOMAttrのオーナー要素であるdivが、その子要素であるpタグやspanタグ、またはdiv要素自身を引数に渡すとtrueが返されます。反対に、オーナー要素とは関係のないbody要素や、まだ文書に追加されていない新しいa要素を引数に渡した場合にはfalseが返されます。このように、特定の要素とその子孫の関係性を手軽に確認できる便利なメソッドです。
DOMAttr::contains()メソッドは、リファレンスと異なり真偽値（true/false）を返します。このメソッドは、属性そのものではなく、その属性が属する要素（owner element）が、引数で渡されたDOMNodeを子孫として含んでいるか、またはDOMNodeがowner element自身であるかを判定します。引数にはDOMNodeインスタンスを指定し、文書内に属さないノードを渡した場合は含まれないと判断されますのでご注意ください。メソッドの理解には、owner elementの概念を把握することが重要です。