【PHP8.x】Dom\TokenList::replace()メソッドの使い方
replaceメソッドの使い方について、初心者にもわかりやすく解説します。
基本的な使い方
『replaceメソッドは、トークンリスト内に存在する特定のトークンを、新しいトークンに置き換える処理を実行するメソッドです。このメソッドは、HTML要素のclass属性値のように、スペースで区切られた文字列の集合を管理する Dom\TokenList オブジェクトに対して使用します。第一引数には置き換えたい既存のトークンを文字列で指定し、第二引数にはその代わりとなる新しいトークンを文字列で指定します。メソッドを実行すると、トークンリストの中から第一引数で指定されたトークンが検索され、見つかった場合は第二引数のトークンに置き換えられます。処理が成功し、トークンが置き換えられた場合は true を返します。もし、指定した既存のトークンがリスト内に存在しなかった場合は、何も変更は行われず、false が返されます。この戻り値を確認することで、置き換え処理が実際に行われたかどうかを判断できます。なお、引数に空文字列や空白文字を含むトークンを指定しようとすると、Dom\Exception というエラーが発生するため注意が必要です。
構文(syntax)
1<?php 2 3$document = new Dom\Document; 4$document->loadHTML('<div class="a b c"></div>'); 5$element = $document->getElementsByTagName('div')[0]; 6 7$tokenList = $element->classList; 8 9// トークン 'b' を 'z' に置き換えます。 10$tokenList->replace('b', 'z'); 11 12// 結果: <div class="a z c"></div> 13echo $document->saveHTML($element); 14 15?>
引数(parameters)
string $token, string $newToken
- string $token: 置換対象のトークンを指定する文字列
- string $newToken: 置換後の新しいトークンを指定する文字列
戻り値(return)
bool
指定されたトークンリスト内で、古いトークンを新しいトークンに置き換える操作が成功したかどうかを示す真偽値を返します。成功した場合はtrue、失敗した場合はfalseを返します。
サンプルコード
PHP Dom\TokenList::replace でクラス名を置き換える
1<?php 2 3/** 4 * Dom\TokenList::replace の使用例を示します。 5 * 6 * この関数は、HTML要素のクラスリスト（class属性）内の特定のトークン（クラス名）を 7 * 別のトークンに置き換えるデモンストレーションを行います。 8 * 9 * Dom\TokenList::replace は、引数に指定された文字列と完全に一致するトークンを置き換えます。 10 * 正規表現によるパターンマッチングは行いません。 11 */ 12function demonstrateTokenListReplace(): void 13{ 14 // HTMLコンテンツを準備 15 $html = '<!DOCTYPE html> 16 <html> 17 <body> 18 <div class="item active featured special">Hello World</div> 19 </body> 20 </html>'; 21 22 // DOMDocumentオブジェクトを作成し、HTMLを読み込む 23 // PHP 8.0以降では、libxmlのエラーはデフォルトで例外をスローしない 24 $dom = new DOMDocument(); 25 @$dom->loadHTML($html, LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD); 26 27 // div要素を取得 28 $element = $dom->getElementsByTagName('div')->item(0); 29 30 // Dom\TokenListオブジェクトを取得 (PHP 8.0以降で利用可能) 31 $tokenList = $element->classList; 32 33 // 置き換え前のクラス属性を表示 34 echo "置き換え前のクラス: " . $element->getAttribute('class') . PHP_EOL; 35 36 // 'featured' トークンを 'archived' に置き換える 37 // 戻り値は成功した場合に true を返す 38 $result = $tokenList->replace('featured', 'archived'); 39 40 if ($result) { 41 echo "'featured' を 'archived' に置き換えました。" . PHP_EOL; 42 } 43 44 // 置き換え後のクラス属性を表示 45 echo "置き換え後のクラス: " . $element->getAttribute('class') . PHP_EOL; 46 47 // 存在しないトークンを置き換えようとする場合 48 echo PHP_EOL; 49 echo "存在しない 'old' を置き換えようとします..." . PHP_EOL; 50 $resultNotFound = $tokenList->replace('old', 'new'); 51 52 if (!$resultNotFound) { 53 echo "トークン 'old' が見つからなかったため、置き換えは行われませんでした。" . PHP_EOL; 54 } 55 echo "最終的なクラス: " . $element->getAttribute('class') . PHP_EOL; 56} 57 58// 関数を実行 59demonstrateTokenListReplace();
Dom\TokenList::replaceメソッドは、HTML要素のclass属性に含まれる特定のクラス名（トークン）を、別の新しいクラス名に置き換えるための機能です。
サンプルコードでは、まずHTML文字列を解析してdiv要素を取得し、その要素のclassListプロパティにアクセスしています。そして、$tokenList->replace('featured', 'archived')を呼び出すことで、class属性値の中から'featured'という文字列を探し出し、それを'archived'という文字列に置き換えています。
第一引数$tokenには置き換えたい既存のクラス名を、第二引数$newTokenには新しいクラス名を文字列で指定します。重要な点として、このメソッドは引数で指定された文字列と完全に一致するクラス名のみを置き換えるため、正規表現によるパターン検索は行いません。
メソッドの戻り値は真偽値（bool）です。置き換え対象のクラス名が存在し、処理が成功した場合にはtrueを返します。対象のクラス名が見つからなかった場合は何もせず、falseを返します。サンプルコードでは、この戻り値を使って置き換えが成功したかどうかを判定し、結果に応じたメッセージを表示しています。
Dom\TokenList::replaceメソッドは、HTML要素のclass属性など、スペースで区切られたリスト内の特定の単語（トークン）を、別の単語に置き換えるためのものです。注意点として、このメソッドは正規表現には対応しておらず、引数で指定した文字列と完全に一致する単語のみを置き換えます。部分的に一致する単語は対象外です。メソッドの戻り値は処理が成功したかを示す真偽値（bool）であり、置き換え対象の単語が見つからなかった場合はfalseを返します。そのため、if文などで戻り値を確認し、意図通りに処理が実行されたかを検証することが重要です。この機能はPHP 8以降のDOM操作で利用できます。
PHPでDom\TokenList::replaceを複数回使う
1<?php 2 3/** 4 * DOM要素のクラスリストから複数のトークンを置換するサンプル関数 5 * 6 * Dom\TokenList::replace() は一度に1つのトークンしか置換できないため、 7 * 複数のトークンを置換したい場合は、ループ処理でメソッドを繰り返し呼び出します。 8 * 9 * @return void 10 */ 11function replaceMultipleClassTokens(): void 12{ 13 // HTMLドキュメントの準備 14 $html = <<<HTML 15 <!DOCTYPE html> 16 <html> 17 <body> 18 <div id="target" class="item active featured">ターゲット要素</div> 19 </body> 20 </html> 21 HTML; 22 23 // DOMDocumentオブジェクトを作成し、HTMLを読み込む 24 $dom = new \Dom\Document(); 25 $dom->loadHTML($html, LIBXML_NOERROR); 26 27 // IDを使って対象のDOM要素を取得 28 $element = $dom->getElementById('target'); 29 30 // 置換したいトークン（クラス名）のペアを連想配列で定義 31 // 'キー' => '置換後の値' 32 $replacements = [ 33 'active' => 'inactive', 34 'featured' => 'standard', 35 ]; 36 37 // 処理前のクラスリストを取得して表示 38 // $element->classList は Dom\TokenList オブジェクトを返す 39 $tokenList = $element->classList; 40 echo "置換前のクラス: " . $element->getAttribute('class') . PHP_EOL; 41 42 // 定義したペアをループで処理し、トークンを置換 43 foreach ($replacements as $oldToken => $newToken) { 44 // トークンが存在する場合にのみ置換を実行 45 if ($tokenList->contains($oldToken)) { 46 $tokenList->replace($oldToken, $newToken); 47 echo " - '${oldToken}' を '${newToken}' に置換しました。" . PHP_EOL; 48 } 49 } 50 51 // 処理後のクラスリストを表示 52 echo "置換後のクラス: " . $element->getAttribute('class') . PHP_EOL; 53 54 // 変更が反映されたHTML全体を出力 55 echo PHP_EOL . "変更後のHTML:" . PHP_EOL; 56 echo $dom->saveHTML(); 57} 58 59// 関数を実行 60replaceMultipleClassTokens();
Dom\TokenList::replace()は、DOM要素が持つクラスリストのようなトークンの中から、指定したトークンを新しいトークンに置き換えるメソッドです。
第1引数 $token には置換したい元のトークン（クラス名など）を文字列で指定し、第2引数 $newToken には置換後の新しいトークンを文字列で指定します。メソッドの戻り値は真偽値（bool）で、置換が成功した場合は true を、指定した $token が存在せず置換できなかった場合は false を返します。
このサンプルコードは、一つのDOM要素が持つ複数のクラス名を一度に置換する方法を示しています。replace()メソッドは一度に一つのトークンしか置換できません。そのため、コードでは置換したいクラス名のペアを連想配列で定義し、foreachループを使ってreplace()メソッドを繰り返し呼び出すことで、複数の置換を実現しています。具体的には、div要素のclass属性に含まれるactiveをinactiveに、featuredをstandardにそれぞれ置換し、最終的なクラスリストをitem inactive standardに変更しています。
Dom\TokenList::replace()メソッドは、一度に一つのクラス名しか置換できません。そのため、サンプルコードのように複数のクラスを一度に置換したい場合は、foreachなどのループ処理でメソッドを繰り返し呼び出す必要があります。注意点として、このメソッドは置換対象のクラス名が存在しなくてもエラーにはならず、単に処理が失敗するだけです。意図しない動作を防ぐため、事前にcontains()メソッドで存在を確認してから置換を行うのがより安全な記述です。また、classListプロパティは、文字列としてクラス属性を操作するより安全で確実な方法です。一連の操作はメモリ上のデータを変更するだけなので、最終的に変更後のHTML文字列を取得するにはsaveHTML()を呼び出すのを忘れないようにしましょう。