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

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

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

基本的な使い方

toggleメソッドは、Dom\TokenListオブジェクトに含まれるトークンを追加または削除する、切り替え操作を実行するメソッドです。第一引数に指定されたトークンがリスト内に存在する場合、そのトークンは削除されます。逆に、トークンが存在しない場合は追加されます。この動作は、ユーザーのアクションに応じて特定のCSSクラスを要素に付けたり外したりするような、動的な状態変化を実装する際に特に便利です。さらに、オプションの第二引数としてブール値を渡すことで、動作を強制的に指定することも可能です。第二引数にtrueを指定すると、トークンの有無にかかわらず常に追加処理が行われます。一方、falseを指定すると常に削除処理が行われます。このメソッドは、操作が完了した後のトークンの存在状態をブール値で返します。最終的にトークンがリスト内に存在する場合はtrueを、存在しない場合はfalseを返すため、処理結果を簡単に確認できます。

構文(syntax)


1<?php
2// $tokenList は Dom\TokenList のインスタンスとします。
3
4// 構文1: トークンの有無を切り替える
5// public function toggle(string $token): bool
6$tokenList->toggle('class-name');
7
8// 構文2: トークンを強制的に追加または削除する
9// public function toggle(string $token, ?bool $force = null): bool
10$tokenList->toggle('class-to-add', true);
11$tokenList->toggle('class-to-remove', false);

引数(parameters)

string $token, ?bool $force = null

string $token: 追加または削除するトークン名を指定する文字列
?bool $force = null: boolean 値を指定して、トークンを強制的に追加または削除するかどうかを制御します。true を指定するとトークンは追加され、false を指定するとトークンは削除されます。null を指定すると、トークンが存在しない場合は追加され、存在する場合は削除されます。

戻り値(return)

bool

指定されたトークンがトークンリストに追加された場合はtrueを、削除された場合はfalseを返します。

サンプルコード

PHP Dom\TokenList toggle でクラスを切り替える


1<?php
2
3/**
4 * Dom\TokenList::toggle の使用例を示します。
5 *
6 * このメソッドは、要素のクラスリストから指定したクラス名の有無を切り替えます。
7 * 第2引数に boolean を渡すことで、追加または削除を強制できます。
8 *
9 * @see https://www.php.net/manual/ja/dom-tokenlist.toggle.php
10 */
11function demonstrateClassListToggle(): void
12{
13    // 操作対象となるHTMLとDOMDocumentオブジェクトを作成します
14    $html = '<!DOCTYPE html><html><body><p class="active visible">Hello World</p></body></html>';
15    $dom = new DOMDocument();
16    // HTML5の要素でエラーが出ないように読み込みます
17    @$dom->loadHTML($html, LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD);
18
19    // p要素のclassList (Dom\TokenList オブジェクト) を取得します
20    $element = $dom->getElementsByTagName('p')->item(0);
21    $classList = $element->classList;
22
23    echo '初期状態のクラス: ' . $element->getAttribute('class') . PHP_EOL;
24    echo '---' . PHP_EOL;
25
26    // パターン1: トークンが存在する場合 ('active'を削除)
27    // 'active'クラスは存在するため、toggleはそれを削除し、falseを返します。
28    $result = $classList->toggle('active');
29    echo "toggle('active') の戻り値: " . ($result ? 'true' : 'false') . PHP_EOL;
30    echo '変更後のクラス: ' . $element->getAttribute('class') . PHP_EOL;
31    echo '---' . PHP_EOL;
32
33    // パターン2: トークンが存在しない場合 ('hidden'を追加)
34    // 'hidden'クラスは存在しないため、toggleはそれを追加し、trueを返します。
35    $result = $classList->toggle('hidden');
36    echo "toggle('hidden') の戻り値: " . ($result ? 'true' : 'false') . PHP_EOL;
37    echo '変更後のクラス: ' . $element->getAttribute('class') . PHP_EOL;
38    echo '---' . PHP_EOL;
39
40    // パターン3: 第2引数(force)にtrueを指定 ('active'を強制的に追加)
41    // 'active'は現在ありませんが、第2引数がtrueなので強制的に追加されます。
42    // メソッドはtrueを返します。
43    $result = $classList->toggle('active', true);
44    echo "toggle('active', true) の戻り値: " . ($result ? 'true' : 'false') . PHP_EOL;
45    echo '変更後のクラス: ' . $element->getAttribute('class') . PHP_EOL;
46    echo '---' . PHP_EOL;
47
48    // パターン4: 第2引数(force)にfalseを指定 ('visible'を強制的に削除)
49    // 'visible'は存在しますが、第2引数がfalseなので強制的に削除されます。
50    // メソッドはfalseを返します。
51    $result = $classList->toggle('visible', false);
52    echo "toggle('visible', false) の戻り値: " . ($result ? 'true' : 'false') . PHP_EOL;
53    echo '変更後のクラス: ' . $element->getAttribute('class') . PHP_EOL;
54}
55
56// 関数を実行してデモを表示します
57demonstrateClassListToggle();

PHPのDom\TokenList::toggle()メソッドは、HTML要素のクラスリストから特定のクラス名の有無を切り替えるために使用します。JavaScriptにおけるelement.classList.toggle()と同様の機能を提供します。

第1引数$tokenには、対象となるクラス名を文字列で指定します。このクラス名が要素のクラスリストに既に存在する場合は削除され、存在しない場合は追加されます。

オプションの第2引数$forceにboolean値（trueまたはfalse）を指定することで、クラスの追加または削除を強制的に実行できます。$forceにtrueを渡すと、そのクラスが存在するかどうかにかかわらずクラスが追加されます。逆にfalseを渡すと、クラスは強制的に削除されます。

このメソッドの戻り値はboolean型です。メソッド実行後の結果として、指定したクラス名がクラスリストに存在している場合はtrueを、存在しない場合はfalseを返します。サンプルコードでは、これらの基本的な切り替え動作と、第2引数による強制的な操作がどのように機能するかを示しています。

この toggle メソッドは、HTML要素の classList プロパティに対して使用します。メソッドの戻り値は、処理の成否ではなく、実行後に指定したクラスが存在するかどうかを示す boolean 値です。true ならクラスが存在し、false なら存在しない状態を表します。第2引数に true を渡すとクラスを強制的に追加し、false を渡すと強制的に削除できます。この引数を使うと、クラスの有無にかかわらず追加または削除の動作が確定します。注意点として、第1引数で指定するクラス名に空白文字を含めることはできません。複数のクラスを一度に操作することはできないため、クラスごとにメソッドを呼び出す必要があります。

PHPでHTMLクラスをtoggleする


1<?php
2
3/**
4 * HTMLボタン要素のクラスを toggle メソッドで切り替えるサンプルコード
5 *
6 * この関数は、PHPのDOM拡張機能を使用してHTMLコンテンツを操作します。
7 * 特定のボタン要素の classList に対して toggle メソッドを実行し、
8 * 'active' クラスの追加と削除を実演します。
9 */
10function toggleButtonClassExample(): void
11{
12    // 操作対象となるシンプルなHTMLを定義
13    $html = <<<HTML
14<!DOCTYPE html>
15<html>
16<head>
17    <title>Toggle Button Example</title>
18    <style>
19        .btn { padding: 8px 16px; border: 1px solid #ccc; cursor: pointer; }
20        .active { background-color: #007bff; color: white; border-color: #007bff; }
21    </style>
22</head>
23<body>
24    <button id="myBtn" class="btn">Click Me</button>
25</body>
26</html>
27HTML;
28
29    // DOMDocumentオブジェクトを生成し、HTMLを読み込む
30    // HTML5の要素を正しく解釈するため、エラーを抑制しています
31    $dom = new DOMDocument();
32    @$dom->loadHTML($html, LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD);
33
34    // IDを指定してボタン要素を取得する
35    $button = $dom->getElementById('myBtn');
36
37    // 要素が取得できたか確認
38    if ($button === null) {
39        echo "指定されたIDのボタンが見つかりませんでした。";
40        return;
41    }
42
43    echo "初期状態のクラス: " . $button->getAttribute('class') . "\n";
44    echo "--- トグル開始 ---\n\n";
45
46    // 1. 'active' クラスをトグルする (クラスが存在しないので追加される)
47    // toggleメソッドは、操作後にクラスが存在する場合に true を返します
48    $isActive = $button->classList->toggle('active');
49    echo "[1] toggle('active')実行後\n";
50    echo "  クラス: " . $button->getAttribute('class') . "\n";
51    echo "  戻り値: " . ($isActive ? 'true' : 'false') . " (activeクラスが追加されました)\n\n";
52
53    // 2. もう一度 'active' クラスをトグルする (クラスが存在するので削除される)
54    $isActive = $button->classList->toggle('active');
55    echo "[2] toggle('active')実行後\n";
56    echo "  クラス: " . $button->getAttribute('class') . "\n";
57    echo "  戻り値: " . ($isActive ? 'true' : 'false') . " (activeクラスが削除されました)\n\n";
58
59    // 3. 第2引数 (force) に true を指定し、'active' クラスを強制的に追加する
60    $isActive = $button->classList->toggle('active', true);
61    echo "[3] toggle('active', true)実行後\n";
62    echo "  クラス: " . $button->getAttribute('class') . "\n";
63    echo "  戻り値: " . ($isActive ? 'true' : 'false') . " (activeクラスが強制的に追加されました)\n\n";
64
65    // 4. 第2引数 (force) に false を指定し、'active' クラスを強制的に削除する
66    $isActive = $button->classList->toggle('active', false);
67    echo "[4] toggle('active', false)実行後\n";
68    echo "  クラス: " . $button->getAttribute('class') . "\n";
69    echo "  戻り値: " . ($isActive ? 'true' : 'false') . " (activeクラスが強制的に削除されました)\n\n";
70
71    echo "--- 最終的なHTML ---\n";
72    echo $dom->saveHTML();
73}
74
75// サンプル関数を実行
76toggleButtonClassExample();

このサンプルコードは、PHPのDom\TokenListクラスに属するtoggleメソッドの動作を解説するものです。このメソッドは、HTML要素のclass属性に含まれる特定のクラス名の有無を切り替える、つまり存在すれば削除し、存在しなければ追加する機能を提供します。

toggleメソッドの第1引数には、操作対象となるクラス名を文字列で指定します。サンプルコードでは、toggle('active')を最初に実行すると、ボタン要素にactiveクラスが追加されます。続けて同じメソッドを呼び出すと、今度はactiveクラスが削除され、元の状態に戻ります。

このメソッドの戻り値は真偽値（bool）です。メソッドの実行後に指定したクラスが存在する状態になればtrueを、存在しない状態になればfalseを返します。これにより、クラスが追加されたのか削除されたのかを判定できます。

また、オプションの第2引数にtrueまたはfalseを指定すると、動作を強制できます。trueを指定するとクラスの有無に関わらず常に追加し、falseを指定すると常に削除します。この機能により、単純な切り替えだけでなく、条件に応じてクラスの状態を確実に制御することが可能です。

このコードは、PHPを用いてサーバー側でHTML要素のクラスを操作する方法を示しています。toggleメソッドは、指定したクラスが存在しない場合は追加し、存在する場合は削除する便利な機能です。第2引数にtrueを指定するとクラスを強制的に追加、falseなら強制的に削除します。戻り値は、操作後にそのクラスが存在する場合にtrueを返します。getElementByIdで要素が見つからないとnullが返るため、次の処理へ進む前に必ずnullでないかを確認することが重要です。この処理はサーバー上で行われるため、ユーザーのクリック操作に応じてリアルタイムに表示を切り替えるには、JavaScriptを用いるのが一般的です。