Dom\TokenList — Klasse · PHP-Referenz

Signatur

class Dom\TokenList implements Countable, IteratorAggregate

Beschreibung

Dom\TokenList ist die PHP-Entsprechung des DOM-DOMTokenList-Interfaces aus der W3C-Spezifikation. Sie wird typischerweise über die Eigenschaft classList eines Dom\Element-Objekts abgerufen und ermöglicht das einfache Hinzufügen, Entfernen, Prüfen und Umschalten von CSS-Klassen oder anderen leerzeichengetrennten Token-Werten eines HTML/XML-Attributs.

Im Gegensatz zur direkten Manipulation des class-Attribut-Strings bietet TokenList eine komfortable objektorientierte API: Methoden wie add(), remove(), contains() und toggle() erlauben es, einzelne Tokens gezielt zu bearbeiten, ohne versehentlich andere Werte zu überschreiben oder doppelte Einträge zu erzeugen.

Das Objekt ist iterierbar (implementiert IteratorAggregate) und zählbar (implementiert Countable), sodass die enthaltenen Tokens bequem mit foreach durchlaufen oder deren Anzahl mit count() ermittelt werden kann. Änderungen an der TokenList spiegeln sich unmittelbar im zugrundeliegenden DOM-Attribut wider.

Dom\TokenList gehört zur neuen, modernen DOM-Erweiterung Dom\, die mit PHP 8.4 eingeführt wurde und die ältere DOMDocument-API ergänzt bzw. ablöst. Sie steht nur in Verbindung mit Klassen wie Dom\HTMLDocument oder Dom\XMLDocument zur Verfügung.

Beispiele

CSS-Klassen eines Elements über classList manipulieren

<?php
$html = Dom\HTMLDocument::createFromString('<div class="box active">Inhalt</div>', LIBXML_NOERROR);
$div = $html->querySelector('div');

$classList = $div->classList;

// Vorhandene Klassen ausgeben
echo 'Anzahl Klassen: ' . count($classList) . PHP_EOL; // 2

foreach ($classList as $token) {
    echo $token . PHP_EOL;
}

// Neue Klasse hinzufügen
$classList->add('highlight');
echo $div->getAttribute('class') . PHP_EOL; // box active highlight

// Klasse entfernen
$classList->remove('active');
echo $div->getAttribute('class') . PHP_EOL; // box highlight

// Prüfen, ob eine Klasse vorhanden ist
var_dump($classList->contains('box'));      // bool(true)
var_dump($classList->contains('active'));   // bool(false)

// Klasse umschalten (toggle)
$classList->toggle('hidden');
echo $div->getAttribute('class') . PHP_EOL; // box highlight hidden
$classList->toggle('hidden');
echo $div->getAttribute('class') . PHP_EOL; // box highlight

Anzahl Klassen: 2 box active box active highlight box highlight bool(true) bool(false) box highlight hidden box highlight

Token ersetzen und Position abfragen

<?php
$html = Dom\HTMLDocument::createFromString('<button class="btn btn-primary">Klick mich</button>', LIBXML_NOERROR);
$button = $html->querySelector('button');

$classList = $button->classList;

// Token ersetzen: btn-primary → btn-danger
$classList->replace('btn-primary', 'btn-danger');
echo $button->getAttribute('class') . PHP_EOL; // btn btn-danger

// Position eines Tokens abfragen
echo $classList->item(0) . PHP_EOL; // btn
echo $classList->item(1) . PHP_EOL; // btn-danger

// Den gesamten Wert als String ausgeben
echo $classList->value . PHP_EOL; // btn btn-danger

btn btn-danger btn btn-danger btn btn-danger

// Wichtig · Fallstricke

Nur mit der neuen Dom\-API verfügbar: Dom\TokenList steht ausschließlich im Kontext der neuen Dom\HTMLDocument- bzw. Dom\XMLDocument-Klassen zur Verfügung, die mit PHP 8.4 eingeführt wurden. Die ältere DOMDocument-Klasse bietet keine TokenList-Unterstützung.

Keine doppelten Tokens: Die Methode add() fügt einen Token nur dann ein, wenn er noch nicht in der Liste vorhanden ist. Dadurch bleiben CSS-Klassenlisten konsistent und frei von Duplikaten.

Leerzeichenregeln: Token dürfen keine ASCII-Leerzeichen enthalten. Beim Versuch, einen Token mit Leerzeichen hinzuzufügen, wird eine Exception ausgelöst. Dies entspricht dem Verhalten der Browserspezifikation.

Siehe auch

Dom\HTMLDocument Dom\XMLDocument Dom\Element Dom\NamedNodeMap Dom\NodeList