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

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

作成日: 2025年09月11日更新日: 2025年11月20日

基本的な使い方

toggleAttributeメソッドは、DOM要素の属性の存在を切り替えるメソッドです。具体的には、指定された名前の属性が要素に存在する場合、その属性を削除します。逆に、属性が存在しない場合、指定された値を持つ属性を要素に追加します。このメソッドは、属性の追加と削除を一つの操作で効率的に行うことを目的としています。

Dom\Elementクラスのメソッドとして提供されており、要素の属性を動的に変更する必要がある場合に便利です。例えば、CSSクラスの追加や削除、ARIA属性の切り替えなど、JavaScriptと連携して動的なUIを実現する際に利用できます。

引数として、切り替えたい属性の名前（文字列）と、属性が存在しない場合に設定する値（文字列）を受け取ります。属性名のみを指定した場合、属性が存在しなければ空文字列が属性値として設定されます。このメソッドは、属性の存在をBoolean的な値として扱い、属性の追加/削除をトグルスイッチのように機能させる点で有用です。

戻り値はvoid型であり、値を返しません。メソッドの実行結果は、DOM要素の属性が直接変更されることで確認できます。エラーが発生した場合、例えばメモリ不足などの深刻な問題が発生した場合は、例外がスローされる可能性があります。そのため、適切なエラーハンドリングを行うことが推奨されます。toggleAttributeメソッドを使用することで、DOM操作をより簡潔にし、コードの可読性を向上させることができます。

構文(syntax)


1public Dom\Element::toggleAttribute(string $name): bool

引数(parameters)

string $qualifiedName, ?bool $force = null

string $qualifiedName: 追加または削除する属性の名前を指定する文字列
?bool $force = null: trueを指定すると属性を強制的に追加または削除し、falseを指定すると属性が存在しない場合にのみ追加、存在する場合にのみ削除します。nullの場合は、属性が存在しない場合は追加し、存在する場合は削除します。

戻り値(return)

void

このメソッドは、指定された属性が存在しない場合は追加し、存在する場合は削除します。属性の追加または削除のみが行われるため、戻り値はありません。

サンプルコード

PHP DOM toggleAttributeで属性を切り替える


1<?php
2
3// このスクリプトは PHP 8.0 以降で動作します。
4// Dom\Element クラスは PHP の DOM 拡張機能の一部で、HTML要素の操作を可能にします。
5
6/**
7 * Dom\Element::toggleAttribute メソッドの動作を示すサンプルコードです。
8 * このメソッドは、HTML要素の指定された属性を切り替え（追加または削除）ます。
9 * システムエンジニアを目指す初心者にも分かりやすいように、各ステップでHTMLの変更を確認できるようにしています。
10 */
11function demonstrateToggleAttribute(): void
12{
13    // 1. 新しいHTMLドキュメントを作成します。
14    // Dom\HTMLDocument は HTML5 のパースとシリアライズをサポートします。
15    $document = new Dom\HTMLDocument();
16
17    // 2. ドキュメントの body 要素を取得します。
18    // HTMLDocument は自動的に基本的なHTML構造（<html>, <head>, <body>）を作成します。
19    $body = $document->body;
20
21    // 3. <button>要素 (Dom\Element のインスタンス) を作成し、body に追加します。
22    $button = $document->createElement('button', 'インタラクティブボタン');
23    $button->id = 'myButton'; // 要素に一意のIDを設定しておくと識別しやすくなります
24    $body->appendChild($button); // 作成したボタンをbodyに追加します
25
26    echo "--- 初期状態 ---\n";
27    // 現在のHTML構造を出力して、ボタン要素に属性がないことを確認します。
28    echo $document->saveHTML() . "\n\n";
29
30    // 4. toggleAttribute() を使用して 'disabled' 属性をトグル（切り替え）ます。
31    // 第2引数 $force が null (デフォルト) の場合：
32    //   - 指定された属性が要素に存在しない場合は、属性が追加されます。
33    //   - 指定された属性が要素に既に存在する場合は、属性が削除されます。
34    
35    // 現在 'disabled' 属性は存在しないため、この呼び出しによって追加されます。
36    $button->toggleAttribute('disabled');
37    echo "--- disabled 属性を追加 (toggle: 属性なし -> 属性あり) ---\n";
38    // 出力されるHTMLで、<button disabled="disabled"> のようになっていることを確認してください。
39    echo $document->saveHTML() . "\n\n";
40
41    // 5. 再度 toggleAttribute() を呼び出すと、'disabled' 属性は削除されます。
42    // 現在 'disabled' 属性は存在するため、この呼び出しによって削除されます。
43    $button->toggleAttribute('disabled');
44    echo "--- disabled 属性を削除 (toggle: 属性あり -> 属性なし) ---\n";
45    // 出力されるHTMLで、<button> から disabled 属性がなくなっていることを確認してください。
46    echo $document->saveHTML() . "\n\n";
47
48    // 6. toggleAttribute() の第2引数に true を指定して、属性を強制的に追加します。
49    // 'data-active' というカスタム属性を追加します。
50    // $force = true の場合、属性が存在しなくても追加され、既に存在していても変更はありません。
51    $button->toggleAttribute('data-active', true);
52    echo "--- data-active 属性を強制追加 (force = true) ---\n";
53    // 出力されるHTMLで、<button data-active="data-active"> のようになっていることを確認してください。
54    echo $document->saveHTML() . "\n\n";
55
56    // 7. toggleAttribute() の第2引数に false を指定して、属性を強制的に削除します。
57    // 現在 'data-active' 属性は存在するため、この呼び出しによって削除されます。
58    // $force = false の場合、属性が存在すれば削除され、存在しなくても変更はありません。
59    $button->toggleAttribute('data-active', false);
60    echo "--- data-active 属性を強制削除 (force = false) ---\n";
61    // 出力されるHTMLで、<button> から data-active 属性がなくなっていることを確認してください。
62    echo $document->saveHTML() . "\n\n";
63
64    // 8. もう一度、別の属性で強制追加の例を見てみましょう。
65    // 例えば、ARIA属性 (アクセシビリティ関連の属性) をトグルする際に便利です。
66    // 'aria-pressed' 属性を強制的に追加します。
67    $button->toggleAttribute('aria-pressed', true);
68    echo "--- aria-pressed 属性を強制追加 (force = true) ---\n";
69    // 出力されるHTMLで、<button aria-pressed="aria-pressed"> のようになっていることを確認してください。
70    echo $document->saveHTML() . "\n\n";
71}
72
73// 上で定義した関数を実行して、サンプルコードの動作を開始します。
74demonstrateToggleAttribute();

PHPのDom\Element::toggleAttributeメソッドは、HTML要素の属性を効率的に追加したり削除したりするために使用される便利な機能です。このメソッドはPHP 8から導入され、HTML要素を表現するDom\Elementクラスに属しています。

このメソッドを使うには、まず第一引数に操作したい属性の名前を文字列で指定します。例えば、「disabled」や「data-active」といったHTML属性名です。

第二引数$forceはオプションで、属性の追加または削除をどのように行うかを制御します。もし$forceをnull（デフォルト値）のまま呼び出すと、メソッドは自動的に属性の状態を切り替えます。つまり、指定された属性が要素にまだ存在しない場合は追加し、既に存在する場合は削除します。これにより、同じメソッドを繰り返し呼び出すだけで、属性をオン・オフのようにトグルできます。

$forceにtrueを指定して呼び出すと、指定された属性は常に要素に追加されます。既にその属性が存在する場合でも、変更は行われません。一方、$forceにfalseを指定して呼び出すと、指定された属性は常に要素から削除されます。元々その属性が存在しなくても、エラーにはなりません。

このメソッドは属性の状態を変更するだけで、特に値を返しません（戻り値はvoidです）。サンプルコードでは、ボタン要素に対してdisabled属性やカスタム属性を、これらの挙動に沿って追加・削除する様子が具体的なHTML出力とともに確認できます。

このサンプルコードはPHP 8.0以降のDOM拡張機能を利用します。Dom\Element::toggleAttributeメソッドを使う際は、第2引数$forceの挙動を正確に理解することが重要です。この引数を省略またはnullにすると、属性が存在しなければ追加し、存在すれば削除する「トグル」動作をします。trueを指定すると属性を強制的に追加し、falseを指定すると強制的に削除しますので、意図しない属性の追加や削除を防ぐために注意が必要です。このメソッドは属性の有無を切り替えるもので、属性に特定の値を設定したい場合はsetAttributeメソッドを使用してください。PHPの実行環境でDOM拡張機能が有効になっていることを事前に確認してください。本メソッドは戻り値がないため、実行後の状態は別途確認が必要です。

PHPでtoggleAttributeを使い属性を切り替える


1<?php
2
3/**
4 * Dom\Element::toggleAttribute() メソッドの基本的な使用例を示します。
5 * HTML要素の 'hidden' 属性を追加・削除することで表示状態を切り替える、
6 * jQueryの属性トグルに似た動作をPHPのDOM操作で実現します。
7 */
8function demonstrateToggleAttribute(): void
9{
10    // DOMドキュメントを作成し、出力されるHTMLを見やすく整形します。
11    $dom = new DOMDocument('1.0', 'UTF-8');
12    $dom->formatOutput = true;
13
14    // 操作対象となるHTML要素（ここではdiv）を作成し、ドキュメントに追加します。
15    $toggleElement = $dom->createElement('div', 'この要素の表示状態が切り替わります。');
16    $toggleElement->setAttribute('id', 'myToggleElement');
17    // 簡単なスタイルを適用して、要素の存在を目視しやすくします。
18    $toggleElement->setAttribute('style', 'border: 1px solid blue; padding: 10px; margin: 10px;');
19    
20    // 作成した要素をDOMドキュメントのルートに追加します。
21    $dom->appendChild($toggleElement);
22
23    echo "--- 初期状態 (hidden属性なし) ---\n";
24    // 現在のDOM構造をHTML形式で出力して確認します。
25    echo $dom->saveHTML() . "\n";
26
27    // 1回目のトグル操作: 'hidden' 属性を追加します。
28    // Dom\Element::toggleAttribute() メソッドの第2引数を省略（nullの場合）すると、
29    // 属性が存在しなければ追加し、存在すれば削除します。
30    // この時点では'hidden'属性が存在しないため、追加されます。
31    $toggleElement->toggleAttribute('hidden');
32    echo "--- 1回目のトグル後 (hidden属性が追加されました) ---\n";
33    echo $dom->saveHTML() . "\n";
34
35    // 2回目のトグル操作: 'hidden' 属性を削除します。
36    // この時点では'hidden'属性が存在するため、削除されます。
37    $toggleElement->toggleAttribute('hidden');
38    echo "--- 2回目のトグル後 (hidden属性が削除されました) ---\n";
39    echo $dom->saveHTML() . "\n";
40}
41
42// 関数を実行して、Dom\Element::toggleAttribute() の動作を確認します。
43demonstrateToggleAttribute();

PHP 8で導入されたDom\Element::toggleAttribute()メソッドは、HTML要素の属性を効率的に追加・削除するための機能です。このメソッドは、指定された属性名を持つ属性が存在しない場合は追加し、既に存在する場合は削除するという、JavaScriptのjQueryライブラリの属性トグル機能に似た動作をPHPのDOM操作で実現します。

引数について、string $qualifiedNameには操作したい属性名を文字列で指定します。例えば、HTMLの表示を制御する'hidden'属性などがこれにあたります。?bool $force = nullは属性の追加・削除を強制するかどうかを決めます。この引数をnull（省略時）にすると、現在の属性の有無に応じてトグル動作が行われます。具体的には、属性がなければ追加し、あれば削除します。trueを指定すると属性は常に強制的に追加され、falseを指定すると常に削除されます。このメソッドの戻り値はvoidであり、何も値を返しません。

サンプルコードでは、まず<div>要素を作成し、初期状態ではhidden属性がない状態で出力します。その後、$toggleElement->toggleAttribute('hidden')を一度呼び出すと、hidden属性が追加され、要素が非表示になる状態を表現します。さらに同じメソッドをもう一度呼び出すと、今度はhidden属性が削除され、要素が再び表示される状態に戻ります。このように、このメソッドはHTML要素の表示・非表示の切り替えなど、属性の状態を簡単に管理する際に非常に役立ちます。

Dom\Element::toggleAttribute()は、PHPでHTML要素の属性をサーバーサイドで追加・削除するためのメソッドです。jQueryのようにブラウザでリアルタイムに表示を切り替えるものではなく、生成されるHTML文字列を操作する点にご注意ください。第1引数には対象の属性名を正確な文字列で指定します。第2引数$forceを省略（null）すると、属性が存在しなければ追加し、存在すれば削除される挙動になります。trueを指定すると強制的に属性が追加され、falseだと強制的に削除されます。この機能はPHP 8以降で利用可能であり、古いバージョンでは動作しませんのでご注意ください。メソッドの戻り値はvoidであり、操作の成否を直接確認するものではありません。