【PHP8.x】Dom\TokenList::supports()メソッドの使い方

supportsメソッドの使い方について、初心者にもわかりやすく解説します。

作成日: 2025年09月11日更新日: 2025年12月15日

基本的な使い方

『supportsメソッドは、Dom\TokenListオブジェクトが関連付けられている属性で、指定されたトークンが仕様上サポートされているかどうかを判定するメソッドです。HTMLの属性の中には、<link>要素のrel属性のように、stylesheetやiconといった特定のキーワードしか値として許可されていないものがあります。このメソッドは、そのような属性に対して、引数で指定したトークンが有効な値として定義されているかを検証するために使用されます。指定したトークンがその属性でサポートされていればtrueを、そうでなければfalseを返します。この機能は、トークンが現在の属性値に実際に含まれているかを確認するcontainsメソッドとは異なります。supportsメソッドは、値の存在有無ではなく、その属性の仕様としてトークンが妥当であるかをチェックする役割を担います。引数として渡すトークンが空文字列であったり、空白文字を含んでいたりするとDOMExceptionというエラーが発生するため注意が必要です。

構文(syntax)


1<?php
2
3$document = new Dom\Document();
4$element = $document->createElement('div');
5
6// Dom\TokenList オブジェクトを取得します
7$tokenList = $element->classList;
8
9// public Dom\TokenList::supports(string $token): bool
10$isSupported = $tokenList->supports('some-class');
11
12var_dump($isSupported);

引数(parameters)

string $token

string $token: サポートされているかどうかを確認したいトークンを指定する文字列

戻り値(return)

bool

このメソッドは、引数として渡されたCSSトークンが、この Dom\TokenList オブジェクトでサポートされているかどうかを示す真偽値（trueまたはfalse）を返します。

サンプルコード

PHP Dom\TokenList::supports() の例外を試す


1<?php
2
3declare(strict_types=1);
4
5/**
6 * Dom\TokenList::supports() の使用例を示す関数
7 *
8 * このメソッドは、属性が特定のトークンをサポートしているかを検証するために定義されています。
9 * しかし、PHPのDOM拡張機能の現在の実装では、この検証はサポートされておらず、
10 * 呼び出すと常に Dom\Exception\UnsupportedOperationException がスローされます。
11 * このサンプルでは、try-catchブロックを使用してその挙動を示します。
12 */
13function checkTokenSupport(): void
14{
15    // HTMLドキュメントを扱うためのDOMDocumentオブジェクトを作成
16    $dom = new \DOMDocument();
17
18    // 簡単なHTMLを読み込む
19    $html = '<!DOCTYPE html>
20    <html>
21    <body>
22        <div id="target" class="class1 class2"></div>
23    </body>
24    </html>';
25    $dom->loadHTML($html);
26
27    // IDを指定して要素を取得
28    $element = $dom->getElementById('target');
29
30    // 要素のクラスリスト（Dom\TokenListオブジェクト）を取得
31    $classList = $element->classList;
32
33    // 検証したいトークン名
34    $token = 'class1';
35
36    try {
37        // supports()メソッドを呼び出す
38        // ここで例外が発生することが期待される
39        $isSupported = $classList->supports($token);
40
41        // この行は通常実行されません
42        echo $isSupported
43            ? "トークン '{$token}' はサポートされています。" . PHP_EOL
44            : "トークン '{$token}' はサポートされていません。" . PHP_EOL;
45
46    } catch (\Dom\Exception\UnsupportedOperationException $e) {
47        // 期待通り例外がスローされた場合の処理
48        echo "Dom\TokenList::supports() は現在サポートされていないため、例外がスローされました。" . PHP_EOL;
49        echo "例外メッセージ: " . $e->getMessage() . PHP_EOL;
50    }
51}
52
53// 関数を実行して結果を確認
54checkTokenSupport();

このサンプルコードは、PHPのDom\TokenListクラスに含まれるsupports()メソッドの使用例を示しています。このメソッドは、HTML要素の属性が特定のトークン（クラス名など）をサポートしているかを検証するために定義されています。引数$tokenには、検証したいトークン名を文字列として渡します。本来、戻り値としてはサポートされていればtrue、されていなければfalseというbool値（真偽値）が返されることが期待されます。

しかし、現在のPHPのDOM実装ではこの機能はサポートされていません。そのため、supports()メソッドを呼び出すと、処理が成功・失敗に関わらず、常にDom\Exception\UnsupportedOperationExceptionという例外が発生します。

このサンプルでは、まずHTMLから特定のdiv要素を取得し、そのクラスリストに対してsupports()メソッドを実行しています。そして、try-catch構文を用いて、意図通りに例外が発生することを実証しています。catchブロックで例外を捕捉し、メソッドがサポートされていない旨のメッセージを出力することで、このメソッドの現在の挙動を明確に示しています。

Dom\TokenList::supports()メソッドは、ドキュメント上はトークンがサポートされているか真偽値を返すとされていますが、現在のPHPバージョンでは実装されていません。そのため、このメソッドを呼び出すと必ずDom\Exception\UnsupportedOperationExceptionという例外が発生し、プログラムがエラーで停止してしまいます。もしこのメソッドを使用する場合は、サンプルコードのようにtry-catchブロックで例外を必ず捕捉する必要があります。ただし、例外を捕捉しても本来の検証機能は使えないため、現時点ではこのメソッドを実際のアプリケーション開発で利用することは避けてください。クラス名に特定のトークンが含まれているかを確認したい場合は、代わりにcontains()メソッドの使用を推奨します。

Dom\TokenList::supports() をループでチェックする


1<?php
2
3/**
4 * PHPがサポートするループ技術（foreach）とDom\TokenList::supports()メソッドの使用例を示します。
5 *
6 * この関数は、HTML要素のクラスリスト（Dom\TokenList）に対して、
7 * 配列に含まれる複数のトークン（クラス名候補）が構文的にサポートされているかを
8 * foreachループを使って一つずつチェックし、結果を出力します。
9 */
10function checkTokenSupportWithLoop(): void
11{
12    // DOMDocumentオブジェクトを生成し、HTMLを読み込みます。
13    $dom = new \Dom\Document();
14    // PHP 8.1以降では、空の文字列を読み込ませるだけで基本的な構造が作られます。
15    $dom->loadHTML(''); 
16
17    // 新しいdiv要素を作成します。
18    $element = $dom->createElement('div');
19
20    // div要素のクラスリスト（Dom\TokenListオブジェクト）を取得します。
21    $tokenList = $element->classList;
22
23    // チェック対象のトークンの配列を定義します。
24    // 有効なトークンと、構文的に無効なトークン（スペースを含むなど）を混ぜています。
25    $tokens = [
26        'valid-class',
27        'another_class',
28        'invalid class', // スペースを含むため無効
29        'single',
30        '',              // 空文字列は無効
31        'with-!char',    // ほとんどの記号は有効
32    ];
33
34    echo "以下のトークンがDom\\TokenListでサポートされているかチェックします...\n";
35    echo "--------------------------------------------------------\n";
36
37    // foreachループを使用して、配列内の各トークンを処理します。
38    // これがPHPの代表的なループ技術の一つです。
39    foreach ($tokens as $token) {
40        // Dom\TokenList::supports()メソッドを呼び出します。
41        // このメソッドは、引数のトークンがDOMのトークンとして構文的に有効な場合にtrueを返します。
42        // トークンに空白文字が含まれている場合などはfalseを返します。
43        if ($tokenList->supports($token)) {
44            echo "✅ トークン '{$token}' はサポートされています。\n";
45        } else {
46            echo "❌ トークン '{$token}' はサポートされていません。\n";
47        }
48    }
49}
50
51// 関数を実行して結果を表示します。
52checkTokenSupportWithLoop();

このPHPコードは、HTML要素のクラス名として使用できる文字列のルールをチェックする Dom\TokenList::supports() メソッドの使用例です。また、PHPの代表的なループ構文である foreach の使い方についても示しています。

supports() メソッドは、引数として受け取った文字列 $token が、DOMのトークン（HTMLのclass属性に指定できる個々のクラス名）として構文的に有効かどうかを判定します。判定結果は真偽値（bool）で返され、有効な文字列の場合は true、スペースを含んでいたり空文字列であったりして無効な場合は false となります。

サンプルコードでは、複数のトークン候補を格納した配列 $tokens を用意し、foreach ループを使って要素を一つずつ取り出しています。ループ内の処理で supports() メソッドを呼び出し、それぞれのトークンが有効かどうかをチェックし、その結果に応じたメッセージを出力します。このように foreach を使うことで、複数のデータに対して同じ処理を効率的に繰り返すことができます。

Dom\TokenList::supports()メソッドは、引数の文字列がHTMLのクラス名として構文的に正しいかを判定します。このメソッドは、クラスが要素に「既に追加されているか」を調べるものではなく、あくまで「ルール上使えるか」をチェックする点に注意が必要です。例えば、スペースを含む文字列や空の文字列はクラス名として使えないためfalseを返します。ユーザーからの入力値をクラス名として動的に設定する際、事前にこのメソッドで検証することで、無効な値がHTMLに適用されるのを防ぎ、より安全なコードを記述できます。foreachループは、このように配列の各要素に対して同じ処理を繰り返す場合に非常に便利な構文です。