【PHP8.x】Dom\TokenList::valueプロパティの使い方

valueプロパティの使い方について、初心者にもわかりやすく解説します。

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

基本的な使い方

『valueプロパティは、Dom\TokenListオブジェクトが表現するトークンリスト全体を、スペースで区切られた単一の文字列として保持するプロパティです。HTML文書を操作する際、要素が持つclass属性のように、複数の値をスペースで区切って指定する属性があります。Dom\TokenListは、これらの値を個別のトークンとして管理しますが、valueプロパティを使うと、それらのトークンを連結した元の属性値そのままの文字列として取得できます。例えば、ある要素のクラスが"alert success"の場合、その要素のTokenListオブジェクトのvalueプロパティは、文字列"alert success"を返します。また、このプロパティは読み取りだけでなく、書き込みも可能です。valueプロパティに新しい文字列を代入すると、関連付けられている属性の値がその文字列で完全に置き換えられます。これにより、属性値を一度にまとめて変更することができます。個々のトークンを追加・削除するadd()やremove()メソッドとは対照的に、属性値全体を文字列として直接扱いたい場合にこのプロパティを使用します。』

構文(syntax)


1<?php
2
3// DOMドキュメントを準備します
4$document = new \Dom\Document();
5$document->loadHTML('<!DOCTYPE html><p class="c1 c2"></p>');
6
7// p要素を取得します
8$element = $document->getElementsByTagName('p')[0];
9
10// Dom\TokenListオブジェクトのvalueプロパティでクラスを文字列として取得します
11$currentValue = $element->classList->value;
12
13// string(5) "c1 c2"
14var_dump($currentValue);
15
16// valueプロパティに新しい文字列を代入してクラスを上書きします
17$element->classList->value = 'c3 c4 c5';
18
19// 変更が反映されていることを確認します
20echo $document->saveHTML($element); // <p class="c3 c4 c5"></p>
21
22?>

引数(parameters)

引数なし

引数はありません

戻り値(return)

string

このプロパティは、Dom\TokenList オブジェクトに含まれるトークンをスペース区切りで連結した文字列を返します。

サンプルコード

PHP Dom\TokenList::$valueでValueErrorを処理する


1<?php
2
3/**
4 * 指定されたDOM要素のクラスリストの値を更新し、不正な値が渡された場合にValueErrorをスローします。
5 *
6 * Dom\TokenList::$value は、要素のclass属性を文字列として直接操作します。
7 * このサンプルでは、アプリケーションのルールとして「空の文字列」を不正な値とみなし、
8 * PHP 8で導入された ValueError をスローして処理します。
9 *
10 * @param \Dom\Element $element クラスを更新するDOM要素
11 * @param string $newValue 新しいクラスの値（スペース区切りの文字列）
12 * @throws \ValueError $newValueが空文字列の場合
13 * @return void
14 */
15function updateClassValue(\Dom\Element $element, string $newValue): void
16{
17    // アプリケーションの要件として、クラスの値が空文字列であることを許可しない
18    if ($newValue === '') {
19        // 引数の型は正しい(string)が、値が不正な場合にValueErrorをスローする
20        throw new \ValueError('クラスの値として空文字列は許可されていません。');
21    }
22
23    // Dom\TokenList::$value プロパティに値を設定する
24    // これにより、要素のclass属性が更新される
25    $element->classList->value = $newValue;
26}
27
28// DOMドキュメントを作成
29$dom = new \Dom\Document();
30// HTMLを読み込む
31$dom->loadHTML('<!DOCTYPE html><html><body><div id="target" class="initial"></div></body></html>', \LIBXML_HTML_NOIMPLIED | \LIBXML_HTML_NODEFDTD);
32
33// IDを使って要素を取得
34$targetElement = $dom->getElementById('target');
35
36echo '更新前のHTML: ' . $dom->saveHTML($targetElement) . PHP_EOL;
37
38// --- 正常なケース ---
39try {
40    echo '--- 正常な更新を試みます ---' . PHP_EOL;
41    updateClassValue($targetElement, 'class-a class-b');
42    echo '更新成功。' . PHP_EOL;
43    echo '更新後のHTML: ' . $dom->saveHTML($targetElement) . PHP_EOL;
44} catch (\ValueError $e) {
45    echo 'エラーが発生しました: ' . $e->getMessage() . PHP_EOL;
46}
47
48echo PHP_EOL;
49
50// --- ValueErrorが発生するケース ---
51try {
52    echo '--- 不正な値（空文字列）での更新を試みます ---' . PHP_EOL;
53    // 空文字列を渡すと、updateClassValue関数内でValueErrorがスローされる
54    updateClassValue($targetElement, '');
55    echo '更新成功。' . PHP_EOL; // この行は実行されない
56} catch (\ValueError $e) {
57    // スローされたValueErrorをキャッチしてエラーメッセージを表示
58    echo 'エラーをキャッチしました: ' . $e->getMessage() . PHP_EOL;
59}
60
61echo '最終的なHTML: ' . $dom->saveHTML($targetElement) . PHP_EOL;
62
63?>

Dom\TokenList::$valueプロパティは、HTML要素が持つclass属性の値を、スペースで区切られた一つの文字列として取得したり、設定したりするために使用します。このプロパティに文字列を代入すると、要素のclass属性全体がその文字列で上書きされます。

このサンプルコードは、updateClassValueという独自の関数を定義し、DOM要素のクラス値を更新する方法を示しています。この関数は、引数として操作対象のDOM要素と、新しいclass属性の値を文字列として受け取ります。戻り値はありません。

このコードの重要な点は、PHP 8で導入されたValueErrorの扱いです。Dom\TokenList::$value自体は空文字列を受け付けますが、このサンプルではアプリケーションのルールとして空文字列を不正な値と定めています。ValueErrorは、関数の引数の「型」は正しいものの、その「値」が不正な場合にスローされる例外です。コード内では、引数として空文字列が渡された場合に、意図的にValueErrorをスローしています。

実行部分では、まず正常な文字列でクラスが更新される例を示し、次に不正な値である空文字列を渡してValueErrorを発生させています。このスローされた例外をtry...catchブロックで捕捉することで、プログラムが異常終了するのを防ぎ、エラー処理を行う流れを確認できます。

Dom\TokenListのvalueプロパティは、HTML要素のclass属性を一つの文字列として直接設定・取得します。これは既存のクラスをすべて上書きする操作であり、個別にクラスを追加・削除するadd()やremove()メソッドとは異なる点に注意が必要です。サンプルコードで発生しているValueErrorは、このプロパティ自体の仕様ではなく、開発者が「空文字列を許可しない」という独自のルールを設けて意図的に発生させています。PHP 8で導入されたValueErrorは、型は正しいが値が不正な場合に用いる例外で、この例はその典型的な使い方を示しています。try-catch構文でこのようなエラーを捕捉することで、予期せぬ入力があってもプログラムが停止せず、安全に処理を続けることができます。

Dom\TokenListのvalueプロパティでクラス属性を操作する


1<?php
2
3/**
4 * Dom\TokenListのvalueプロパティの使用例を示すクラス
5 *
6 * このサンプルでは、HTML要素のclass属性をDom\TokenListオブジェクトとして操作し、
7 * valueプロパティでその文字列表現を取得する方法を示します。
8 * また、関連キーワードとして挙げられたphp_value memory_limitについても、
9 * 現在の設定値を取得して表示します。
10 */
11class DomTokenListValueExample
12{
13    /**
14     * サンプルコードを実行します。
15     */
16    public function execute(): void
17    {
18        // memory_limitはサーバー設定（例: .htaccessのphp_value memory_limit）で
19        // 指定される値で、ini_get()関数で現在の設定値を取得できます。
20        $memoryLimit = ini_get('memory_limit');
21        echo "現在のPHPメモリ上限 (memory_limit): " . htmlspecialchars($memoryLimit) . PHP_EOL;
22        echo '------------------------------------' . PHP_EOL;
23
24        // 操作対象となるHTML文字列を準備します。
25        $html = '<div id="target" class="foo bar baz"></div>';
26
27        // DOMDocumentを使用してHTMLを解析します。
28        $doc = new \DOMDocument();
29        $doc->loadHTML($html);
30
31        // id属性を元に要素を取得します。
32        $element = $doc->getElementById('target');
33
34        // Dom\Element::classList は Dom\TokenList オブジェクトを返します。
35        $tokenList = $element->classList;
36
37        // Dom\TokenList->value プロパティは、全てのクラス名を
38        // スペースで区切った単一の文字列として返します。
39        $classString = $tokenList->value;
40
41        echo "取得したclass属性の文字列: '{$classString}'" . PHP_EOL;
42
43        // valueプロパティを使ってクラスを直接書き換えることも可能です。
44        $tokenList->value = 'new-class another-class';
45        echo "変更後のclass属性の文字列: '{$tokenList->value}'" . PHP_EOL;
46
47        // 変更がDOMに反映されているか確認します。
48        echo "変更後のHTML: " . $doc->saveHTML($element) . PHP_EOL;
49    }
50}
51
52// クラスのインスタンスを作成し、メソッドを実行します。
53$example = new DomTokenListValueExample();
54$example->execute();

このサンプルコードは、PHPのDom\TokenListクラスが持つvalueプロパティの機能を示しています。Dom\TokenListは、HTML要素のclass属性に含まれる複数のクラス名をまとめて扱うためのオブジェクトです。

valueプロパティは、このDom\TokenListオブジェクトが保持する全てのクラス名を、スペースで区切られた単一の文字列として取得したり、設定したりするために使用します。このプロパティは引数を取らず、値を取得する際の戻り値はstring型となります。

サンプルコードでは、まずHTMLから特定の要素を取得し、そのclassListプロパティからDom\TokenListオブジェクトを得ています。次に、$tokenList->valueとアクセスすることで、'foo bar baz'というclass属性の文字列表現を取得しています。さらに、このvalueプロパティに'new-class another-class'という新しい文字列を代入することで、要素のclass属性全体を一度に書き換えています。

また、関連キーワードであるphp_value memory_limitは、PHPスクリプトが使用できるメモリの最大量を定義するサーバー設定です。コード冒頭のini_get('memory_limit')は、この現在設定されている値を取得するためのPHP関数です。

Dom\TokenList の value プロパティは、HTML要素の class 属性値をスペースで区切られた一つの文字列として扱います。このプロパティに新しい文字列を代入すると、既存のクラスは全て置き換えられる点に注意してください。個別のクラスを追加・削除したい場合は add() や remove() メソッドを使用します。また、コード中にある ini_get('memory_limit') は、Dom\TokenList の機能とは直接関係なく、PHPの実行環境で設定されたメモリ上限値を確認するものです。最後に、取得した値をブラウザに出力する際は、htmlspecialchars 関数でエスケープ処理を行うことがセキュリティ上重要です。