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

Copy
1<?php
2
3// Dom\HTMLDocument クラスを使用するためにインポートします。
4// PHP 8 で導入された新しい DOM API の一部で、HTML ドキュメントを扱うのに特化しています。
5use Dom\HTMLDocument;
6
7/**
8 * Dom\HTMLElement::toggleAttribute メソッドの動作を示すサンプル関数です。
9 *
10 * この関数は、HTML要素の特定の属性の有無を切り替える動作をデモンストレーションします。
11 * システムエンジニアを目指す初心者の方にも理解しやすいように、詳細な出力を含みます。
12 *
13 * @param string $attributeName 切り替えたいHTML属性の名前 (例: 'hidden', 'disabled', 'data-custom')
14 * @param ?bool $force 属性の状態を強制的に設定します。
15 *                     - null (デフォルト): 属性が存在すれば削除し、存在しなければ追加します (現在の状態を反転)。
16 *                     - true: 属性が存在しなくても強制的に追加します。
17 *                     - false: 属性が存在しても強制的に削除します。
18 * @return void
19 */
20function demonstrateToggleAttribute(string $attributeName, ?bool $force = null): void
21{
22    // 新しい HTML ドキュメントオブジェクトを作成します。
23    // Dom\HTMLDocument は、HTML要素の作成と操作を簡単に行えるように設計されています。
24    $document = new HTMLDocument();
25
26    // ドキュメントの body 要素を作成し、ドキュメントツリーに追加します。
27    $body = $document->createElement('body');
28    $document->appendChild($body);
29
30    // テスト用の div 要素を作成し、body 要素に追加します。
31    // Dom\HTMLDocument::createElement() は Dom\HTMLElement のインスタンスを返します。
32    $element = $document->createElement('div');
33    $element->textContent = 'これはID "myElement" を持つテスト要素です。';
34    $element->setAttribute('id', 'myElement');
35    $body->appendChild($element);
36
37    echo "--- 属性 '{$attributeName}' の toggleAttribute 動作確認 (force: " . (is_null($force) ? 'null' : ($force ? 'true' : 'false')) . ") ---\n";
38    echo "初期状態: " . ($element->hasAttribute($attributeName) ? "属性が存在します。\n" : "属性は存在しません。\n");
39    echo "初期HTML: " . htmlspecialchars($document->saveHTML($element)) . "\n";
40
41    // toggleAttribute メソッドを実行し、属性の有無を切り替えます。
42    // メソッドの戻り値は、操作後の属性の存在状態を示すブール値です。
43    $attributeExistsAfterToggle = $element->toggleAttribute($attributeName, $force);
44
45    echo "toggleAttribute() 実行後:\n";
46    echo "  戻り値: " . ($attributeExistsAfterToggle ? "true (属性が存在します)" : "false (属性は存在しません)") . "\n";
47    echo "  現在の状態: " . ($element->hasAttribute($attributeName) ? "属性 '{$attributeName}' が存在します。\n" : "属性 '{$attributeName}' は存在しません。\n");
48    echo "  最終HTML: " . htmlspecialchars($document->saveHTML($element)) . "\n\n";
49}
50
51// --- サンプル実行例 ---
52
53// 例1: 属性が存在しない場合、`force = null` で属性が追加されます。
54// 結果: 属性 'data-active' が追加されます。
55demonstrateToggleAttribute('data-active', null);
56
57// 例2: 属性が存在する場合、`force = null` で属性が削除されます。
58// (前の実行で 'data-active' が追加されているため、今回は削除されます)
59// 結果: 属性 'data-active' が削除されます。
60demonstrateToggleAttribute('data-active', null);
61
62// 例3: 属性が存在しない場合、`force = true` で属性が強制的に追加されます。
63// 結果: 属性 'hidden' が追加されます。
64demonstrateToggleAttribute('hidden', true);
65
66// 例4: 属性が存在する場合、`force = false` で属性が強制的に削除されます。
67// (前の実行で 'hidden' が追加されているため、今回は削除されます)
68// 結果: 属性 'hidden' が削除されます。
69demonstrateToggleAttribute('hidden', false);
70
71// 例5: 別の属性で確認 (属性の追加と削除を連続して確認)
72demonstrateToggleAttribute('disabled', null); // 存在しないので追加される
73demonstrateToggleAttribute('disabled', true);  // 既に存在しても強制的に追加 (変化なしだが戻り値はtrue)
74demonstrateToggleAttribute('disabled', false); // 存在する属性を強制的に削除

Dom\HTMLElement::toggleAttributeは、PHP 8で導入された新しいDOM APIの一部であり、HTML要素の特定の属性の有無を簡単に切り替えるためのメソッドです。Webアプリケーションで要素の表示・非表示や、フォーム要素の有効・無効といった状態を動的に変更する際に非常に便利です。

このメソッドは、第一引数に操作したい属性名（例: 'hidden'や'disabled'）を指定します。第二引数$forceはオプションで、属性の状態を強制的に設定するかどうかを制御します。$forceがnull（デフォルト）の場合、属性が要素に存在すれば削除し、存在しなければ追加するというように、現在の状態を反転させます。trueを指定すると属性が存在しなくても強制的に追加され、falseを指定すると属性が存在しても強制的に削除されます。

メソッドの戻り値はブール値で、toggleAttributeの操作後にその属性が要素に存在するかどうかを示します。サンプルコードでは、まず新しいHTMLドキュメント内にテスト用のdiv要素を作成し、様々な$forceの値を指定してtoggleAttributeを実行しています。初期状態、メソッド実行後の戻り値、および最終的なHTMLの状態を段階的に出力することで、このメソッドの具体的な動作と、属性がどのように追加・削除されるかを初心者の方にも分かりやすくデモンストレーションしています。

Copy
1<?php
2
3use Dom\HTMLDocument;
4use Dom\HTMLElement;
5
6/**
7 * HTML要素の属性をトグルするサンプルコードです。
8 *
9 * この関数は、指定されたHTML文字列から要素をロードし、
10 * その要素の特定の属性（例: 'hidden', 'disabled'）の有無を切り替える方法を示します。
11 * これは、JavaScriptのjQueryライブラリにおける「toggle attribute」機能に似た動作を
12 * PHPのDom\HTMLElement::toggleAttributeメソッドで実現します。
13 *
14 * システムエンジニアを目指す初心者向けに、各ステップで何が起こっているかを
15 * 簡潔なコメントで説明しています。
16 *
17 * @param string $initialHtmlString 操作対象となるHTMLの初期状態を保持する文字列。
18 * @param string $targetElementId 属性をトグルするHTML要素のID。
19 * @param string $attributeToToggle 切り替えたい属性の名前（例: 'hidden', 'disabled'）。
20 */
21function demonstrateToggleAttribute(
22    string $initialHtmlString,
23    string $targetElementId,
24    string $attributeToToggle
25): void {
26    // 1. HTMLドキュメントの準備
27    // Dom\HTMLDocumentは、PHPでHTMLドキュメントを解析し、その構造を操作するためのクラスです。
28    // ブラウザがHTMLページを解釈するのと同様に、PHPコード内でHTML要素を扱えるようになります。
29    $document = new HTMLDocument();
30    // HTML文字列をドキュメントにロードします。
31    $document->loadHTML($initialHtmlString);
32
33    // 2. 操作対象のHTML要素を取得
34    // getElementByIdメソッドを使って、HTMLドキュメント内から特定のIDを持つ要素を探し出します。
35    // 戻り値はDom\HTMLElementオブジェクト、または見つからない場合はnullです。
36    $element = $document->getElementById($targetElementId);
37
38    // 要素が正しく取得できたか確認します。
39    if (!$element instanceof HTMLElement) {
40        echo "エラー: ID '{$targetElementId}' の要素が見つからないか、有効なHTMLElementではありません。\n";
41        return;
42    }
43
44    echo "--- ID '{$targetElementId}' の要素に対する操作 ({$attributeToToggle} 属性) ---\n";
45    echo "初期状態のHTML:\n" . $document->saveHTML() . "\n";
46    echo "初期状態: '{$attributeToToggle}' 属性は " . ($element->hasAttribute($attributeToToggle) ? '存在します' : '存在しません') . "。\n";
47
48    // 3. 属性をトグル (toggleAttributeの基本的な使用方法 - $force = null の場合)
49    // 第2引数 ($force) を指定しない (nullの場合) と、
50    // 属性が存在すれば削除し、存在しなければ追加します。
51    // 戻り値は、属性が追加された場合は true、削除された場合は false です。
52    echo "\n--- 1回目のトグル: 属性の有無を切り替え ---\n";
53    $wasAddedFirstTime = $element->toggleAttribute($attributeToToggle);
54    echo "処理結果: " . ($wasAddedFirstTime ? '属性が追加されました。' : '属性が削除されました。') . "\n";
55    echo "現在の状態: '{$attributeToToggle}' 属性は " . ($element->hasAttribute($attributeToToggle) ? '存在します' : '存在しません') . "。\n";
56
57    // 4. 再び属性をトグル (もう一度切り替えることで元の状態に戻るか、さらに変化します)
58    echo "\n--- 2回目のトグル: 再び属性の有無を切り替え ---\n";
59    $wasAddedSecondTime = $element->toggleAttribute($attributeToToggle);
60    echo "処理結果: " . ($wasAddedSecondTime ? '属性が追加されました。' : '属性が削除されました。') . "\n";
61    echo "現在の状態: '{$attributeToToggle}' 属性は " . ($element->hasAttribute($attributeToToggle) ? '存在します' : '存在しません') . "。\n";
62
63    // 5. 属性を強制的に追加する例 ($force = true)
64    // 属性がすでに存在しても追加の操作は行われませんが、
65    // 確実に存在させたい場合に利用します。
66    echo "\n--- 強制的に属性を追加 ({$attributeToToggle}, true) ---\n";
67    $forcedAdd = $element->toggleAttribute($attributeToToggle, true);
68    echo "処理結果: " . ($forcedAdd ? '属性が追加されました。' : '属性は既に存在していました (または追加されませんでした)。') . "\n";
69    echo "現在の状態: '{$attributeToToggle}' 属性は " . ($element->hasAttribute($attributeToToggle) ? '存在します' : '存在しません') . "。\n";
70
71    // 6. 属性を強制的に削除する例 ($force = false)
72    // 属性が存在しない場合でも削除の操作は行われませんが、
73    // 確実に削除したい場合に利用します。
74    echo "\n--- 強制的に属性を削除 ({$attributeToToggle}, false) ---\n";
75    $forcedRemove = $element->toggleAttribute($attributeToToggle, false);
76    echo "処理結果: " . ($forcedRemove ? '属性が削除されました。' : '属性は既に存在しませんでした (または削除されませんでした)。') . "\n";
77    echo "現在の状態: '{$attributeToToggle}' 属性は " . ($element->hasAttribute($attributeToToggle) ? '存在します' : '存在しません') . "。\n";
78
79    echo "\n--- 最終的なHTML --- \n";
80    echo $document->saveHTML();
81}
82
83// --- サンプルコードの実行例 ---
84
85echo "=== 例1: 'hidden'属性を持たない要素へのトグル ===\n\n";
86demonstrateToggleAttribute(
87    '<div id="myBox">最初のボックス</div><p>これは別の段落です。</p>',
88    'myBox',
89    'hidden'
90);
91
92echo "\n========================================\n\n";
93
94echo "=== 例2: 'disabled'属性を持つ要素へのトグル ===\n\n";
95demonstrateToggleAttribute(
96    '<button id="myButton" disabled>クリックできません</button><input type="text" value="入力フィールド">',
97    'myButton',
98    'disabled'
99);

PHP 8で導入されたDom\HTMLElement::toggleAttributeメソッドは、HTML要素の特定の属性の有無を簡単に切り替える機能を提供します。これはJavaScriptのjQueryライブラリにおける「toggle attribute」機能と似ており、例えば要素の表示/非表示を制御するhidden属性や、要素を操作不能にするdisabled属性などを、PHPで効率的に管理できます。

このメソッドの第1引数$qualifiedNameには、切り替えたい属性の名前を文字列で指定します。第2引数$forceはオプションで、nullを渡すか省略した場合、属性が存在すれば削除し、存在しなければ追加するという基本的なトグル動作を行います。trueを指定すると、属性が既に存在するかどうかにかかわらず、常に属性が追加されるように強制します。反対にfalseを指定すると、属性が既に存在するかどうかにかかわらず、常に属性が削除されるように強制します。メソッドの戻り値はbool型で、属性が追加された場合はtrue、削除された場合はfalseを示します。

サンプルコードでは、初期のHTML文字列からDom\HTMLDocumentを用いて要素をロードし、getElementByIdで対象要素を取得した後、このtoggleAttributeメソッドを使って具体的な属性の切り替え操作を実演しています。これにより、属性の有無が変化する様子や、$force引数を使った強制的な操作の挙動を学ぶことができます。