Dom\HTMLDocument — Klasse · PHP-Referenz

Signatur

class Dom\HTMLDocument extends Dom\Document

Beschreibung

Dom\HTMLDocument ist Teil der neuen, in PHP 8.4 eingeführten Dom-Erweiterung und bietet eine spezifikationskonforme Implementierung des HTML-Dokument-Objektmodells gemäß dem WHATWG-HTML-Standard. Im Unterschied zur älteren DOMDocument-Klasse verarbeitet sie HTML5-Markup korrekt, inklusive moderner Elemente und impliziter Tag-Schließungen.

Dokumente können entweder über die statische Methode Dom\HTMLDocument::createFromString() aus einem HTML-String oder über Dom\HTMLDocument::createFromFile() aus einer Datei geladen werden. Alternativ lässt sich mit Dom\HTMLDocument::createEmpty() ein leeres Dokument erzeugen, das dann programmatisch befüllt wird.

Die Klasse unterstützt moderne Selektoren über querySelector() und querySelectorAll(), womit sich Elemente mit CSS-Selektoren auswählen lassen. Alle Knoten und Elemente sind typisiert und folgen der offiziellen DOM-Spezifikation, was eine deutlich robustere und vorhersehbarere API gegenüber DOMDocument bedeutet.

Für die Verarbeitung von XML-Dokumenten steht die Schwester-Klasse Dom\XMLDocument zur Verfügung. Dom\HTMLDocument ist speziell auf HTML ausgelegt und behandelt zum Beispiel <script>- oder <style>-Inhalte korrekt als Rohtext.

Beispiele

HTML aus einem String laden und mit querySelector auslesen

<?php
$html = <<<HTML
<!DOCTYPE html>
<html>
<body>
  <h1 id="title">Willkommen</h1>
  <ul>
    <li class="item">Eins</li>
    <li class="item">Zwei</li>
    <li class="item">Drei</li>
  </ul>
</body>
</html>
HTML;

$doc = Dom\HTMLDocument::createFromString($html);

$title = $doc->querySelector('#title');
echo $title->textContent . PHP_EOL;

$items = $doc->querySelectorAll('.item');
foreach ($items as $item) {
    echo $item->textContent . PHP_EOL;
}

Willkommen Eins Zwei Drei

Neues HTML-Dokument programmatisch erstellen

<?php
$doc = Dom\HTMLDocument::createEmpty();

$html = $doc->createElement('html');
$doc->appendChild($html);

$body = $doc->createElement('body');
$html->appendChild($body);

$p = $doc->createElement('p');
$p->textContent = 'Hallo, DOM!';
$body->appendChild($p);

echo $doc->saveHTML();

<html><body><p>Hallo, DOM!</p></body></html>

HTML aus einer Datei laden und Elemente manipulieren

<?php
// Annahme: /tmp/page.html enthält valides HTML
file_put_contents('/tmp/page.html', '<html><body><p id="msg">Alt</p></body></html>');

$doc = Dom\HTMLDocument::createFromFile('/tmp/page.html');

$msg = $doc->querySelector('#msg');
$msg->textContent = 'Neu';

echo $doc->saveHTML($msg);

// Wichtig · Fallstricke

Neu in PHP 8.4: Dom\HTMLDocument ist nicht abwärtskompatibel mit DOMDocument. Knoten aus der neuen Erweiterung können nicht in die alte Klasse übertragen werden und umgekehrt.

Zeichencodierung: Beim Parsen wird die Zeichencodierung automatisch aus dem HTML-Meta-Tag ermittelt. Wenn keine angegeben ist, wird UTF-8 angenommen. Übergabe von Nicht-UTF-8-Strings ohne korrekte Deklaration kann zu unerwarteten Ergebnissen führen.

Fehlerbehandlung: Im Gegensatz zu DOMDocument werden Parse-Fehler nicht global über libxml_get_errors() gemeldet. Stattdessen können Fehler über das $options-Argument der Factory-Methoden gesteuert werden.

Sicherheit: Beim Einbinden von Nutzer-Eingaben in HTML-Dokumente sollten Textinhalte ausschließlich über textContent gesetzt werden, niemals als rohes HTML, um XSS-Angriffe zu verhindern.

Siehe auch

Dom\XMLDocument Dom\Document DOMDocument Dom\Element Dom\NodeList