【PHP8.x】Dom\TokenList::item()メソッドの使い方
itemメソッドの使い方について、初心者にもわかりやすく解説します。
基本的な使い方
itemメソッドは、トークンリスト（Dom\TokenListオブジェクト）内の指定されたインデックス（位置）にあるトークンを取得するメソッドです。Dom\TokenListオブジェクトは、HTML要素のclass属性のように、スペースで区切られた複数の文字列（トークン）の集合を管理します。このメソッドを使用することで、リストに含まれる個々のトークンに順番でアクセスすることが可能になります。引数には、取得したいトークンの位置を0から始まる整数のインデックスで指定します。例えば、リストの先頭にあるトークンを取得したい場合はインデックスとして0を、2番目のトークンを取得したい場合は1を指定します。メソッドの返り値は、指定したインデックスにトークンが存在すればそのトークンの文字列となり、存在しない場合、つまりインデックスがリストの範囲外である場合にはnullが返されます。この機能は、TokenListオブジェクトを配列のように扱い、角括弧（[]）を用いて$list[0]のように直接インデックスでアクセスした場合と同じ結果を得ることができます。
構文(syntax)
1<?php 2// HTML文字列からDOMドキュメントを作成します 3$dom = new \DOMDocument(); 4$dom->loadHTML('<p class="token1 token2 token3"></p>'); 5 6// <p>要素を取得します 7$element = $dom->getElementsByTagName('p')->item(0); 8 9// classList (Dom\TokenList) からインデックス1のトークン（クラス名）を取得します 10// インデックスは0から始まります 11$token = $element->classList->item(1); 12 13// "token2" が出力されます 14echo $token; 15?>
引数(parameters)
int $index
- int $index: 取得したい要素のインデックスを指定する整数
戻り値(return)
?string
指定されたインデックスに対応するトークン文字列を返します。指定されたインデックスが存在しない場合は null を返します。
サンプルコード
id="item_id" のクラス名を取得する
1<?php 2 3/** 4 * 指定されたIDを持つHTML要素のクラスリストから、 5 * Dom\TokenList::item() を使って特定のクラス名を取得するサンプル関数です。 6 */ 7function displayClassNameByIndex(): void 8{ 9 // 操作対象のHTML文字列を定義します。 10 // ここでは、idが "item_id" で、複数のクラスを持つdiv要素を用意します。 11 $html = '<!DOCTYPE html> 12 <html> 13 <body> 14 <div id="item_id" class="active featured new">An item</div> 15 </body> 16 </html>'; 17 18 // DOMDocumentオブジェクトをインスタンス化し、HTMLを読み込みます。 19 $dom = new DOMDocument(); 20 $dom->loadHTML($html); 21 22 // getElementById() メソッドで "item_id" を持つ要素を取得します。 23 // 返り値は Dom\Element オブジェクトまたは null です。 24 $element = $dom->getElementById('item_id'); 25 26 // 要素が正しく取得できたか確認します。 27 if ($element instanceof \DOMElement) { 28 // $element->classList は Dom\TokenList オブジェクトを返します。 29 $classList = $element->classList; 30 31 // item() メソッドは、指定したインデックス（0始まり）にあるトークン（クラス名）を返します。 32 // インデックス 0 のクラス名を取得します。 33 $firstClass = $classList->item(0); 34 echo "インデックス 0 のクラス名: " . ($firstClass ?? '見つかりません') . PHP_EOL; 35 36 // インデックス 2 のクラス名を取得します。 37 $thirdClass = $classList->item(2); 38 echo "インデックス 2 のクラス名: " . ($thirdClass ?? '見つかりません') . PHP_EOL; 39 40 // 存在しないインデックスを指定した場合、item() メソッドは null を返します。 41 $nonExistentClass = $classList->item(99); 42 echo "インデックス 99 のクラス名: "; 43 var_dump($nonExistentClass); // 結果は NULL となります。 44 } else { 45 echo "ID 'item_id' を持つ要素が見つかりませんでした。" . PHP_EOL; 46 } 47} 48 49// 作成した関数を実行します。 50displayClassNameByIndex(); 51 52?>
Dom\TokenList::item()メソッドは、HTML要素が持つクラスのリスト（class属性の値）から、特定の位置にあるクラス名を1つ取得するために使用します。このメソッドは、JavaScriptにおけるDOMTokenList.item()と同様の機能を提供します。
このメソッドの引数には、取得したいクラス名の位置を0から始まる数値（インデックス）で指定します。例えば、リストの先頭にあるクラス名を取得したい場合は 0 を、3番目のクラス名を取得したい場合は 2 を指定します。
戻り値は、指定したインデックスにクラス名が存在すれば、そのクラス名が文字列として返されます。もし指定したインデックスが存在しない場合、例えばクラスが3つしかないリストに対して item(99) のように範囲外の位置を指定した場合は、null が返されます。
サンプルコードでは、id="item_id"を持つ要素のクラスリスト "active featured new" に対して item() メソッドを使用しています。item(0) を実行すると1番目の "active" が、item(2) を実行すると3番目の "new" が取得できます。一方、存在しないインデックスである item(99) を実行した場合は null が返るため、エラーを起こすことなくクラスの有無を安全に判定できます。
Dom\TokenList::item()メソッドは、HTML要素のclass属性値を0から始まるインデックスで取得します。注意点は、指定したインデックスにクラス名が存在しない場合、エラーにはならずnullが返されることです。nullをそのまま文字列として扱おうとするとエラーの原因となるため、サンプルコードのように??演算子で代替値を指定したり、if文でnullでないことを確認してから利用するのが安全です。また、getElementById()が正しく機能するには、HTMLに<!DOCTYPE html>のような文書型宣言が必須です。この宣言がないと要素が見つからない点にも気をつけましょう。
PHP Dom\TokenList::item() でインデックス指定してクラス名を取得する
1<?php 2 3declare(strict_types=1); 4 5/** 6 * Dom\TokenList::item() の使用例を示します。 7 * 8 * このメソッドは、HTML要素のclass属性のリスト（TokenList）から、 9 * 配列のようにインデックス番号を指定して、特定のクラス名を取得するために使用します。 10 */ 11function demonstrateTokenListItem(): void 12{ 13 // 1. 操作対象となるHTML文字列を準備します。 14 // class属性に複数のクラス名がスペース区切りで設定されています。 15 $html = '<!DOCTYPE html> 16 <html> 17 <body> 18 <div id="my-element" class="token-one token-two token-three"></div> 19 </body> 20 </html>'; 21 22 // 2. DOMDocumentオブジェクトを使い、HTMLを解析します。 23 $dom = new DOMDocument(); 24 // HTMLのパースエラーを抑制します。 25 @$dom->loadHTML($html); 26 27 // 3. IDを指定して、操作したいHTML要素を取得します。 28 $element = $dom->getElementById('my-element'); 29 if (!$element) { 30 echo '要素が見つかりませんでした。' . PHP_EOL; 31 return; 32 } 33 34 // 4. 要素の `classList` プロパティから Dom\TokenList オブジェクトを取得します。 35 // このオブジェクトは、クラス名のリストを配列のように扱える便利な機能を提供します。 36 $tokenList = $element->classList; 37 38 // 5. item() メソッドを使い、インデックスを指定してクラス名を取得します。 39 // インデックスは0から始まります。配列の $array[1] と同じ考え方です。 40 $secondToken = $tokenList->item(1); 41 echo "インデックス1のクラス名: " . $secondToken . PHP_EOL; 42 43 // 6. 存在しないインデックスを指定すると、戻り値は null となります。 44 $nonExistentToken = $tokenList->item(99); 45 echo "インデックス99のクラス名: "; 46 var_dump($nonExistentToken); 47 48 // 参考: ループですべてのクラス名を取得する例 49 echo "すべてのクラス名:" . PHP_EOL; 50 for ($i = 0; $i < $tokenList->count(); $i++) { 51 echo "- " . $tokenList->item($i) . PHP_EOL; 52 } 53} 54 55// 関数を実行して結果を確認します。 56demonstrateTokenListItem(); 57 58?>
Dom\TokenList::item()メソッドは、HTML要素が持つ複数のクラス名の中から、特定の一つを取得するために使用します。HTMLのclass属性に "class-a class-b" のようにスペースで区切られた複数のクラス名が設定されている場合、Dom\TokenListオブジェクトはこれをリストとして扱います。このメソッドは、そのリストから配列のように番号（インデックス）を指定して、目的のクラス名を取り出す役割を果たします。
引数には、取得したいクラス名の位置を示す$indexを整数で指定します。このインデックスは0から始まります。例えば、2番目のクラス名を取得したい場合は1を指定します。
メソッドの戻り値は、指定したインデックスにクラス名が存在すればそのクラス名（文字列）が返されます。もし、存在しないインデックス（例えば、クラスが3つしかないのにインデックス99を指定するなど）を指定した場合は、nullが返されます。
サンプルコードでは、class="token-one token-two token-three"というクラスを持つ要素に対して$tokenList->item(1)を実行しています。これにより、リストの1番目（2番目）のクラス名である"token-two"という文字列が取得されます。また、存在しないインデックス99を指定した場合はnullが返されることも確認できます。
Dom\TokenList::item()メソッドは、HTML要素のクラス名リストから特定のクラス名を取り出す際に使用します。注意すべき点は、番号の指定が0から始まることです。例えばitem(1)はリストの2番目のクラス名を指します。プログラミングの配列と同じ考え方です。また、存在しない番号を指定した場合、エラーにはならず、戻り値としてnullが返されます。そのため、取得したクラス名を使用する前には、値がnullでないかを確認すると、予期せぬエラーを防ぐことができ安全です。このオブジェクトは配列のように見えますが、item()のような専用のメソッドで操作します。