【PHP8.x】Dom\TokenList::contains()メソッドの使い方
containsメソッドの使い方について、初心者にもわかりやすく解説します。
基本的な使い方
『containsメソッドは、Dom\TokenListオブジェクト内に指定されたトークンが存在するかどうかを真偽値で判定するメソッドです。Dom\TokenListオブジェクトは、HTML要素のclass属性のように、スペースで区切られた複数の文字列（トークン）の集合を効率的に扱うために使用されます。このメソッドは、特定のクラス名が要素に設定されているかを確認する際などに役立ちます。引数には、検索対象となるトークンを文字列で一つ指定します。指定されたトークンがリスト内に存在すればtrueを、存在しなければfalseを返します。この比較処理は、大文字と小文字を厳密に区別して行われるため、完全に一致するトークンが見つかった場合のみtrueが返されます。引数として渡すトークンが空文字列であったり、スペース文字を含んでいたりすると、それらは無効なトークンとみなされ、Dom\Exception例外が発生するため注意が必要です。』
構文(syntax)
1<?php 2 3$doc = new DOMDocument(); 4$doc->loadHTML('<div class="token1 token2"></div>'); 5 6$tokenList = $doc->getElementsByTagName('div')[0]->classList; 7 8// 指定したトークンが含まれている場合は true を返す 9$result1 = $tokenList->contains('token1'); 10var_dump($result1); 11 12// 指定したトークンが含まれていない場合は false を返す 13$result2 = $tokenList->contains('token3'); 14var_dump($result2); 15 16?>
引数(parameters)
string $token
- string $token: 検索するトークン名を指定する文字列
戻り値(return)
bool
指定されたトークンがリストに含まれているかどうかを示します。含まれている場合は true を、含まれていない場合は false を返します。
サンプルコード
PHP Dom\TokenList::contains でクラス名を確認する
1<?php 2 3declare(strict_types=1); 4 5/** 6 * HTML要素のクラスリストに特定のトークン（クラス名）が含まれているかを確認します。 7 * 8 * このサンプルは、PHPのDOM拡張機能を利用しています。 9 * `Dom\TokenList::contains` メソッドは、HTML要素の `class` 属性値などを 10 * 配列のように扱い、特定のクラス名が含まれているかを boolean 値で返します。 11 * これは、一般的なPHP配列で `in_array()` を使うのと似た概念です。 12 * 13 * @param string $htmlContent チェック対象となるHTML文字列。 14 * @param string $elementId 対象要素のID。 15 * @param string $tokenToCheck 存在を確認したいトークン（クラス名）。 16 * @return bool トークンが存在すればtrue、しなければfalse。 17 */ 18function checkClassToken(string $htmlContent, string $elementId, string $tokenToCheck): bool 19{ 20 // DOMDocumentオブジェクトを生成し、HTMLを読み込みます。 21 $doc = new DOMDocument(); 22 // HTMLのパースエラーを抑制します。 23 @$doc->loadHTML($htmlContent, LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD); 24 25 // 指定されたIDを持つ要素を取得します。 26 $element = $doc->getElementById($elementId); 27 28 // 要素が見つからない場合は、falseを返します。 29 if ($element === null) { 30 return false; 31 } 32 33 // Dom\TokenListオブジェクトを取得し、containsメソッドでトークンの存在を確認します。 34 return $element->classList->contains($tokenToCheck); 35} 36 37// --- サンプル実行 --- 38 39// チェック対象のHTML 40$html = '<!DOCTYPE html> 41<html> 42<body> 43 <div id="user-profile" class="card active-user premium-member">ユーザー情報</div> 44</body> 45</html>'; 46 47// 1. 'active-user' クラスが存在するかチェック 48$token1 = 'active-user'; 49$result1 = checkClassToken($html, 'user-profile', $token1); 50 51echo "クラスリストに '{$token1}' は含まれているか？" . PHP_EOL; 52var_dump($result1); // 結果: bool(true) 53 54echo PHP_EOL; 55 56// 2. 'guest' クラスが存在するかチェック 57$token2 = 'guest'; 58$result2 = checkClassToken($html, 'user-profile', $token2); 59 60echo "クラスリストに '{$token2}' は含まれているか？" . PHP_EOL; 61var_dump($result2); // 結果: bool(false) 62
このサンプルコードは、PHPのDOM拡張機能に含まれる Dom\TokenList::contains メソッドの使用例です。このメソッドは、HTML要素の class 属性のように、スペースで区切られた文字列のリスト（トークンリスト）の中に、指定した文字列（トークン）が含まれているかを判定するために使用します。
contains メソッドは、引数として検索したいトークンを文字列で受け取ります。戻り値は bool 型で、トークンがリスト内に存在すれば true を、存在しなければ false を返します。この動作は、PHPの配列内に特定の要素があるかどうかを in_array() 関数で確認する操作と似ています。
サンプルコードでは、まず DOMDocument オブジェクトを生成してHTML文字列を解析し、getElementById で特定の div 要素を取得しています。次に、その要素の classList プロパティ（Dom\TokenList オブジェクト）に対して contains メソッドを呼び出します。これにより、「active-user」というクラス名が存在すること（結果: true）、そして「guest」というクラス名が存在しないこと（結果: false）を正確に確認しています。
Dom\TokenList::containsは、HTMLのclass属性のようなスペース区切りの文字列を扱うための専用メソッドです。PHPの配列関数in_arrayと似ていますが、通常の配列には使えない点に注意してください。このメソッドを使うには、まずDOMDocumentでHTMLを解析し、対象の要素を取得する必要があります。サンプルコードの@$doc->loadHTML()にある@はエラーを抑制しますが、HTMLの構造が不正な場合に問題の発見が遅れる可能性があります。containsメソッドはトークンとの完全一致で判定するため、activeがactive-userに部分一致することはありません。また、対象要素が見つからない場合に備えたnullチェックは、エラーを避けるために重要です。
PHP containsでクラス存在をチェックする
1<?php 2 3/** 4 * HTML要素のクラスリストに特定のクラス名が含まれているかを確認します。 5 * 6 * Dom\TokenList::contains() メソッドは、指定されたトークン（クラス名）が 7 * 要素のクラスリストに存在する場合に true を、存在しない場合に false を返します。 8 */ 9function checkClassExistence(): void 10{ 11 // 検証対象のHTML文字列を定義します。 12 $html = <<<HTML 13 <!DOCTYPE html> 14 <html> 15 <body> 16 <p id="targetElement" class="message important primary">これはテスト用の段落です。</p> 17 </body> 18 </html> 19 HTML; 20 21 // DOMDocumentオブジェクトを作成し、HTMLを読み込みます。 22 // PHP 8.0以降では、ext-dom拡張機能がこの機能を提供します。 23 $dom = new DOMDocument(); 24 25 // HTML5のタグに対する警告を抑制し、DOMを安全に読み込みます。 26 libxml_use_internal_errors(true); 27 $dom->loadHTML($html); 28 libxml_clear_errors(); 29 30 // IDを指定して特定のHTML要素を取得します。 31 $element = $dom->getElementById('targetElement'); 32 33 // 要素のクラスリスト（Dom\TokenListオブジェクト）を取得します。 34 $classList = $element->classList; 35 36 // --- Dom\TokenList::contains() の使用例 --- 37 38 // 1. 存在するクラス名 'important' をチェックします。 39 $token1 = 'important'; 40 $hasToken1 = $classList->contains($token1); 41 42 echo "クラスリストに '{$token1}' は含まれていますか？" . PHP_EOL; 43 var_dump($hasToken1); // bool(true) が出力されます。 44 45 echo PHP_EOL; 46 47 // 2. 存在しないクラス名 'secondary' をチェックします。 48 $token2 = 'secondary'; 49 $hasToken2 = $classList->contains($token2); 50 51 echo "クラスリストに '{$token2}' は含まれていますか？" . PHP_EOL; 52 var_dump($hasToken2); // bool(false) が出力されます。 53} 54 55// 関数を実行して結果を確認します。 56checkClassExistence();
Dom\TokenList::contains()メソッドは、HTML要素のclass属性に、指定したクラス名が含まれているかどうかを判定するために使用します。
サンプルコードでは、まずDOMDocumentクラスを利用してHTML文字列を解析し、getElementById()でid="targetElement"を持つp要素を取得しています。次に、その要素のclassListプロパティからDom\TokenListオブジェクトを取得します。このオブジェクトが、クラス名の一覧を管理しています。
contains()メソッドは、このDom\TokenListオブジェクトに対して呼び出します。引数には、存在を確認したいクラス名を文字列で渡します。サンプルコードの1つ目の例では、クラスリストに存在する'important'を渡しているため、メソッドはtrueを返します。一方、2つ目の例では、存在しない'secondary'を渡しているため、falseが返されます。
このように、contains()メソッドの戻り値は真偽値（bool型）であり、指定したクラス名が存在すればtrue、存在しなければfalseとなります。この結果を利用して、特定のクラスを持つ要素に対して条件分岐処理などを行うことができます。
Dom\TokenList::contains()メソッドは、DOMElementオブジェクトのclassListプロパティに対してのみ使用できる点に注意してください。文字列や配列に直接使うことはできません。引数には、チェックしたいクラス名を1つだけ文字列で指定します。スペースで区切った複数のクラス名を一度に渡すと、意図せずfalseが返ります。また、このメソッドは大文字と小文字を厳密に区別するため、例えば'Important'と'important'は異なるものとして判定されます。この機能はPHP 8.0以降で利用でき、ext-dom拡張機能が有効になっている必要があります。HTML要素が正しく取得できていないとエラーになるため、対象の要素が存在することも事前に確認しましょう。