Wer in PHP mit HTML oder XML arbeitet, kommt an der Klasse DOMDocument kaum vorbei. Ob Web Scraping, das Auslesen von RSS-Feeds, die Generierung von HTML-Mails oder das Verarbeiten von XML-Schnittstellen: Überall dort, wo Dokumente programmatisch geladen, durchsucht oder verändert werden müssen, bietet DOMDocument eine zuverlässige Lösung. Dieses Tutorial erklärt die wichtigsten Methoden zum Laden und Parsen von HTML und XML, zeigt wie Elemente im DOM-Baum gefunden und manipuliert werden, behandelt häufige Stolperfallen wie UTF-8-Probleme und stellt abschließend die neue Klasse Dom\HTMLDocument aus PHP 8.4 vor.
Zum Einstieg werfen wir einen Blick auf die Klasse selbst und ihre Stellung innerhalb der PHP DOM-Extension.
Was ist DOMDocument in PHP?
Die Klasse DOMDocument ist Bestandteil der DOM-Extension in PHP und implementiert den W3C-Standard für das Document Object Model. Sie repräsentiert ein vollständiges HTML- oder XML-Dokument als Baumstruktur, in der jeder Knoten ein Element, ein Attribut oder ein Textinhalt sein kann. Die DOM-Extension ist in den meisten PHP-Installationen bereits aktiviert, da sie auf der weit verbreiteten C-Bibliothek libxml2 aufbaut.
Anders als reguläre Ausdrücke, die bei verschachtelten Strukturen schnell an ihre Grenzen stoßen, arbeitet DOMDocument mit einer echten Baumstruktur und ermöglicht so zuverlässiges Parsen auch bei komplexem Markup. Ein DOMDocument-Objekt wird mit dem Schlüsselwort new erzeugt. Optional lassen sich die XML-Version und das Encoding als Parameter angeben.
<?php
$doc = new DOMDocument('1.0', 'UTF-8');
/* Eigenschaften des Dokuments ausgeben */
echo $doc->xmlVersion;
/* 1.0 */
echo $doc->encoding;
/* UTF-8 */
Das erzeugte Objekt dient als Ausgangspunkt für alle weiteren Operationen. Es bietet Methoden zum Laden von Inhalten, zum Suchen von Elementen und zum Erstellen neuer Knoten. Die Baumstruktur folgt dabei dem bekannten DOM-Prinzip: Das Dokument selbst ist der Wurzelknoten, darunter befinden sich Elemente wie html, head und body, die wiederum Kindelemente enthalten können.
Das folgende Diagramm zeigt den typischen Arbeitsablauf bei der Verwendung von DOMDocument in PHP.
flowchart TD
A["HTML/XML-Quelle"] --> B{"Lademethode"}
B -->|String| C["loadHTML() / loadXML()"]
B -->|Datei| D["loadHTMLFile() / load()"]
C --> E["DOMDocument-Objekt"]
D --> E
flowchart LR
E["DOMDocument-Objekt"] --> F["Elemente suchen"]
E --> G["DOM manipulieren"]
E --> H["Ausgabe erzeugen"]
F --> F1["getElementsByTagName()"]
F --> F2["getElementById()"]
F --> F3["DOMXPath::query()"]
HTML laden und parsen
Bevor Elemente gesucht oder verändert werden können, muss das HTML-Dokument in das DOMDocument-Objekt geladen werden. PHP bietet dafür zwei Methoden an: loadHTML() für Strings und loadHTMLFile() für Dateien.
loadHTML() für HTML-Strings
Die Methode loadHTML() nimmt einen HTML-String entgegen und erzeugt daraus die interne Baumstruktur. Sie interpretiert den Input als HTML und fügt bei Bedarf automatisch DOCTYPE, html und body-Tags hinzu.
<?php
$html = '<div class="inhalt"><p>Hallo Welt</p><p>Zweiter Absatz</p></div>';
$doc = new DOMDocument();
libxml_use_internal_errors(true);
$doc->loadHTML($html);
libxml_clear_errors();
$absaetze = $doc->getElementsByTagName('p');
foreach ($absaetze as $p) {
echo $p->textContent . "\n";
}
/*
Hallo Welt
Zweiter Absatz
*/
Der Aufruf von libxml_use_internal_errors(true) vor dem Laden ist wichtig. Ohne diese Zeile gibt PHP bei fehlerhaftem oder unvollständigem HTML Warnungen aus, die in der Produktion störend sind. Die Funktion weist libxml2 an, Fehler intern zu speichern statt sie direkt auszugeben. Mit libxml_clear_errors() werden die gespeicherten Fehler anschließend gelöscht.
loadHTMLFile() für Dateien
Liegt das HTML in einer Datei vor, kann loadHTMLFile() direkt einen Dateipfad oder eine URL entgegennehmen.
<?php
$doc = new DOMDocument();
libxml_use_internal_errors(true);
$doc->loadHTMLFile('seite.html');
libxml_clear_errors();
$titel = $doc->getElementsByTagName('title');
if ($titel->length > 0) {
echo $titel->item(0)->textContent;
}
Diese Methode eignet sich besonders für das Einlesen lokaler HTML-Dateien. Für das Laden von Webseiten über eine URL ist sie ebenfalls nutzbar, allerdings bieten spezialisierte HTTP-Clients wie Guzzle oder die file_get_contents()-Funktion in Kombination mit loadHTML() oft mehr Kontrolle über HTTP-Header und Timeouts. Der Rückgabewert beider Lademethoden ist true bei Erfolg und false bei einem Fehler. Fehlerdetails lassen sich nach dem Laden mit libxml_get_errors() auslesen, sofern libxml_use_internal_errors(true) zuvor aktiviert wurde.
UTF-8-Probleme und deren Lösung
Eine der häufigsten Stolperfallen bei DOMDocument betrifft die Zeichenkodierung. Die zugrunde liegende libxml2-Bibliothek nimmt standardmäßig ISO-8859-1 an. Enthält der HTML-String UTF-8-kodierte Zeichen wie Umlaute oder Sonderzeichen, werden diese ohne entsprechenden Hinweis fehlerhaft interpretiert.
<?php
/* Problem: Umlaute werden verstümmelt */
$html = '<p>Schöne Grüße</p>';
$doc = new DOMDocument();
libxml_use_internal_errors(true);
/* Lösung: Meta-Tag mit charset voranstellen */
$doc->loadHTML('<meta charset="utf-8">' . $html);
libxml_clear_errors();
echo $doc->saveHTML($doc->getElementsByTagName('p')->item(0));
/* <p>Schöne Grüße</p> */
Durch das Voranstellen eines <meta charset="utf-8">-Tags erkennt der Parser die korrekte Kodierung. Eine alternative Lösung besteht darin, den String vor dem Laden mit mb_convert_encoding($html, 'HTML-ENTITIES', 'UTF-8') in HTML-Entities umzuwandeln. Beide Varianten stellen sicher, dass Sonderzeichen korrekt erhalten bleiben. Dieses Problem tritt besonders häufig auf, wenn HTML-Inhalte aus Datenbanken, API-Antworten oder Benutzereingaben stammen, die in UTF-8 kodiert sind. Ohne den Encoding-Hinweis werden Zeichen außerhalb des ASCII-Bereichs falsch dargestellt oder gehen verloren.
Elemente im DOM suchen
Nachdem ein Dokument geladen wurde, stehen verschiedene Methoden zur Verfügung, um gezielt Elemente im DOM-Baum zu finden. Die Wahl der Methode hängt davon ab, ob nach Tag-Namen, IDs oder komplexeren Mustern gesucht wird.
getElementsByTagName()
Die Methode getElementsByTagName() durchsucht das gesamte Dokument nach Elementen mit einem bestimmten Tag-Namen und gibt eine DOMNodeList zurück.
<?php
$html = '<ul>
<li>PHP</li>
<li>JavaScript</li>
<li>Python</li>
</ul>';
$doc = new DOMDocument();
libxml_use_internal_errors(true);
$doc->loadHTML('<meta charset="utf-8">' . $html);
libxml_clear_errors();
$listeneintraege = $doc->getElementsByTagName('li');
echo 'Anzahl: ' . $listeneintraege->length . "\n";
foreach ($listeneintraege as $eintrag) {
echo $eintrag->textContent . "\n";
}
/*
Anzahl: 3
PHP
JavaScript
Python
*/
Die zurückgegebene DOMNodeList ist iterierbar und bietet über die Eigenschaft length Zugriff auf die Anzahl der gefundenen Elemente. Mit item(0) lässt sich ein einzelnes Element über seinen Index abrufen. Die Methode kann auch auf einzelnen Elementen aufgerufen werden, um nur innerhalb eines Teilbaums zu suchen.
getElementById()
Mit getElementById() wird ein einzelnes Element anhand seines id-Attributs gesucht. Diese Methode funktioniert bei HTML-Dokumenten zuverlässig, da der HTML-Parser das id-Attribut automatisch als ID-Typ erkennt.
<?php
$html = '<div id="hauptbereich">
<h1>Willkommen</h1>
<p>Dies ist der Hauptinhalt.</p>
</div>
<div id="sidebar">
<p>Seitenleiste</p>
</div>';
$doc = new DOMDocument();
libxml_use_internal_errors(true);
$doc->loadHTML('<meta charset="utf-8">' . $html);
libxml_clear_errors();
$hauptbereich = $doc->getElementById('hauptbereich');
if ($hauptbereich !== null) {
echo $hauptbereich->textContent;
}
/*
Willkommen
Dies ist der Hauptinhalt.
*/
Bei XML-Dokumenten ist die Situation anders. Dort muss das id-Attribut entweder über eine DTD als ID-Typ deklariert oder manuell mit DOMElement::setIdAttribute() registriert werden, damit getElementById() funktioniert. Gibt es kein Element mit der angegebenen ID, liefert die Methode null zurück. Eine Prüfung auf null vor dem Zugriff auf Eigenschaften oder Methoden des Elements ist daher ratsam, um Fehler zur Laufzeit zu vermeiden.
XPath-Abfragen mit DOMXPath
Für komplexere Suchanfragen steht die Klasse DOMXPath zur Verfügung. XPath ist eine Abfragesprache, die das Navigieren in XML- und HTML-Dokumenten nach beliebigen Kriterien ermöglicht, darunter Attributwerte, Verschachtelungstiefen und Textinhalte.
<?php
$html = '<ul>
<li class="aktiv">Startseite</li>
<li>Produkte</li>
<li class="aktiv">Kontakt</li>
<li>Impressum</li>
</ul>';
$doc = new DOMDocument();
libxml_use_internal_errors(true);
$doc->loadHTML('<meta charset="utf-8">' . $html);
libxml_clear_errors();
$xpath = new DOMXPath($doc);
/* Alle li-Elemente mit der Klasse "aktiv" finden */
$aktiveElemente = $xpath->query('//li[@class="aktiv"]');
foreach ($aktiveElemente as $element) {
echo $element->textContent . "\n";
}
/*
Startseite
Kontakt
*/
/* Alle li-Elemente zählen */
$anzahl = $xpath->evaluate('count(//li)');
echo 'Gesamtanzahl: ' . $anzahl;
/* Gesamtanzahl: 4 */
Die Methode query() gibt eine DOMNodeList mit den gefundenen Knoten zurück. Die Methode evaluate() kann zusätzlich skalare Werte wie Zahlen oder Strings berechnen. XPath-Ausdrücke beginnen mit // für eine Suche im gesamten Dokument. Eckige Klammern ermöglichen die Filterung nach Attributen. So findet //li[@class="aktiv"] alle li-Elemente, deren class-Attribut den Wert aktiv hat. Weitere nützliche XPath-Ausdrücke sind //a[@href] für alle Links mit einem href-Attribut, //div/p für alle p-Elemente, die direkte Kinder eines div sind, und //p[contains(text(), "Suchwort")] für Absätze, die einen bestimmten Text enthalten. DOMXPath ist das mächtigste Werkzeug zum Durchsuchen von DOM-Strukturen und eignet sich besonders für Web Scraping und die Verarbeitung komplexer XML-Dokumente.
Den DOM-Baum manipulieren
Neben dem Auslesen von Inhalten ermöglicht DOMDocument auch das Erstellen, Einfügen und Entfernen von Elementen. Damit lassen sich Dokumente programmatisch aufbauen oder bestehende Strukturen gezielt verändern. Das ist beispielsweise beim Generieren von HTML-Mails, beim Erzeugen von XML-Exports oder beim nachträglichen Anpassen von HTML-Fragmenten hilfreich.
Neue Elemente erstellen
Mit createElement() wird ein neues Element erzeugt, mit createTextNode() ein reiner Textknoten. Beide Methoden geben ein neues Knotenobjekt zurück, das anschließend in den Baum eingefügt werden muss.
<?php
$doc = new DOMDocument('1.0', 'UTF-8');
/* Container-Element erstellen */
$container = $doc->createElement('div');
$container->setAttribute('class', 'wrapper');
/* Überschrift mit Text erstellen */
$ueberschrift = $doc->createElement('h1');
$text = $doc->createTextNode('Meine Seite');
$ueberschrift->appendChild($text);
/* Absatz erstellen */
$absatz = $doc->createElement('p', 'Willkommen auf der Seite.');
/* Elemente in den Container einfügen */
$container->appendChild($ueberschrift);
$container->appendChild($absatz);
/* Container zum Dokument hinzufügen */
$doc->appendChild($container);
echo $doc->saveHTML();
/*
<div class="wrapper"><h1>Meine Seite</h1><p>Willkommen auf der Seite.</p></div>
*/
Die Methode createElement() akzeptiert einen optionalen zweiten Parameter für den Textinhalt des Elements. Für komplexere Inhalte empfiehlt sich die Verwendung von createTextNode() in Kombination mit appendChild(). Das erzeugte Element existiert zunächst nur im Speicher und wird erst durch appendChild() oder insertBefore() Teil des Dokumentbaums.
Elemente einfügen und entfernen
Das Einfügen neuer Knoten erfolgt über appendChild() am Ende eines Elternelements oder über insertBefore() vor einem bestimmten Geschwisterelement. Zum Entfernen dient removeChild().
<?php
$html = '<ul id="liste">
<li>Erster Eintrag</li>
<li>Zweiter Eintrag</li>
</ul>';
$doc = new DOMDocument();
libxml_use_internal_errors(true);
$doc->loadHTML('<meta charset="utf-8">' . $html);
libxml_clear_errors();
$liste = $doc->getElementById('liste');
/* Neues Element am Ende einfügen */
$neuerEintrag = $doc->createElement('li', 'Dritter Eintrag');
$liste->appendChild($neuerEintrag);
/* Erstes li-Element entfernen */
$erstesLi = $liste->getElementsByTagName('li')->item(0);
$liste->removeChild($erstesLi);
echo $doc->saveHTML($liste);
/*
<ul id="liste">
<li>Zweiter Eintrag</li>
<li>Dritter Eintrag</li></ul>
*/
Beim Entfernen von Elementen muss beachtet werden, dass removeChild() auf dem Elternelement aufgerufen wird, nicht auf dem zu entfernenden Element selbst. Das entfernte Element wird als Rückgabewert zurückgegeben und kann bei Bedarf an anderer Stelle wieder eingefügt werden. Neben appendChild() und removeChild() stehen auch replaceChild() zum Ersetzen eines Knotens durch einen anderen und cloneNode() zum Kopieren eines vorhandenen Knotens samt seiner Kindelemente zur Verfügung.
Attribute setzen und auslesen
Attribute werden über die Methoden setAttribute(), getAttribute() und removeAttribute() verwaltet. Die Methode hasAttribute() prüft, ob ein bestimmtes Attribut vorhanden ist.
<?php
$html = '<a href="https://example.com" class="link">Beispiel</a>';
$doc = new DOMDocument();
libxml_use_internal_errors(true);
$doc->loadHTML('<meta charset="utf-8">' . $html);
libxml_clear_errors();
$link = $doc->getElementsByTagName('a')->item(0);
/* Attribut auslesen */
echo $link->getAttribute('href') . "\n";
/* https://example.com */
/* Attribut setzen */
$link->setAttribute('target', '_blank');
$link->setAttribute('rel', 'noopener');
/* Attribut prüfen */
if ($link->hasAttribute('class')) {
echo 'Klasse: ' . $link->getAttribute('class') . "\n";
/* Klasse: link */
}
/* Attribut entfernen */
$link->removeAttribute('class');
echo $doc->saveHTML($link);
/* <a href="https://example.com" target="_blank" rel="noopener">Beispiel</a> */
Attribute lassen sich beliebig hinzufügen, ändern und entfernen. Das ist besonders nützlich, wenn bestehende HTML-Strukturen nachträglich angepasst werden sollen, etwa um Links mit target="_blank" und rel="noopener" zu versehen. Ein weiterer häufiger Anwendungsfall ist das Hinzufügen von CSS-Klassen oder data-Attributen zu bestehenden Elementen. Die Kombination aus getElementsByTagName() und setAttribute() ermöglicht es, alle Elemente eines bestimmten Typs in einer Schleife zu durchlaufen und deren Attribute einheitlich zu setzen oder zu aktualisieren.
XML laden und verarbeiten
Neben HTML kann DOMDocument auch XML-Dokumente laden und verarbeiten. Die Methoden load() für Dateien und loadXML() für Strings arbeiten mit strikter XML-Syntax und fügen keine zusätzlichen Tags hinzu.
<?php
$xml = '<?xml version="1.0" encoding="UTF-8"?>
<produkte>
<produkt id="1">
<name>Laptop</name>
<preis>999.99</preis>
</produkt>
<produkt id="2">
<name>Maus</name>
<preis>29.99</preis>
</produkt>
<produkt id="3">
<name>Tastatur</name>
<preis>79.99</preis>
</produkt>
</produkte>';
$doc = new DOMDocument();
$doc->loadXML($xml);
$produkte = $doc->getElementsByTagName('produkt');
foreach ($produkte as $produkt) {
$name = $produkt->getElementsByTagName('name')->item(0)->textContent;
$preis = $produkt->getElementsByTagName('preis')->item(0)->textContent;
$id = $produkt->getAttribute('id');
echo "ID: $id, Name: $name, Preis: $preis EUR\n";
}
/*
ID: 1, Name: Laptop, Preis: 999.99 EUR
ID: 2, Name: Maus, Preis: 29.99 EUR
ID: 3, Name: Tastatur, Preis: 79.99 EUR
*/
Im Gegensatz zu loadHTML() ist loadXML() strenger bei der Validierung. Nicht wohlgeformtes XML führt zu Fehlern. Auch bei XML empfiehlt sich der Einsatz von libxml_use_internal_errors(true), um Warnungen bei kleinen Unstimmigkeiten abzufangen. Die Ausgabe erfolgt über saveXML(), das im Unterschied zu saveHTML() die XML-Deklaration und selbstschließende Tags beibehält. Typische Anwendungsfälle für loadXML() sind das Verarbeiten von RSS-Feeds, Sitemaps, SOAP-Antworten und Konfigurationsdateien. Auch XPath-Abfragen lassen sich auf XML-Dokumente genauso anwenden wie auf HTML.
HTML und XML als String ausgeben
Nach dem Manipulieren eines Dokuments muss das Ergebnis häufig wieder als String ausgegeben oder in eine Datei geschrieben werden. Dafür stehen die Methoden saveHTML() und saveXML() zur Verfügung.
<?php
$doc = new DOMDocument('1.0', 'UTF-8');
$doc->formatOutput = true;
$root = $doc->createElement('html');
$body = $doc->createElement('body');
$absatz = $doc->createElement('p', 'Formatierte Ausgabe');
$body->appendChild($absatz);
$root->appendChild($body);
$doc->appendChild($root);
/* Gesamtes Dokument als HTML */
echo $doc->saveHTML();
/* Einzelnes Element als HTML */
echo $doc->saveHTML($absatz);
/* <p>Formatierte Ausgabe</p> */
/* Gesamtes Dokument als XML */
echo $doc->saveXML();
Die Eigenschaft formatOutput sorgt für eine eingerückte, lesbare Ausgabe. Ohne diese Einstellung wird das gesamte HTML in einer einzigen Zeile ausgegeben. Beide Methoden akzeptieren einen optionalen Parameter, um nur einen bestimmten Knoten statt des gesamten Dokuments auszugeben. Das ist besonders hilfreich, wenn nur ein Fragment und nicht das vollständige Dokument mit DOCTYPE und html-Tag benötigt wird. Zusätzlich existiert die Eigenschaft preserveWhiteSpace, die vor dem Laden gesetzt werden muss und steuert, ob Leerräume im Quelldokument beibehalten werden. Eine häufige Kombination ist $doc->preserveWhiteSpace = false zusammen mit $doc->formatOutput = true, um das Dokument zunächst kompakt einzulesen und dann sauber formatiert auszugeben.
Neues in PHP 8.4: Dom\HTMLDocument
PHP 8.4 führt mit Dom\HTMLDocument eine neue Klasse ein, die einen standardkonformen HTML5-Parser verwendet. Im Gegensatz zum klassischen DOMDocument, das auf dem veralteten HTML4-Parser von libxml2 basiert, kann Dom\HTMLDocument moderne HTML5-Konstrukte korrekt verarbeiten.
<?php
/* Ab PHP 8.4 verfügbar */
$html = '<div><p>Hallo <strong>Welt</strong></p></div>';
/* Dokument aus String erstellen */
$doc = Dom\HTMLDocument::createFromString($html);
/* Elemente suchen */
$absaetze = $doc->getElementsByTagName('p');
foreach ($absaetze as $p) {
echo $p->textContent . "\n";
}
/* Hallo Welt */
/* Aus Datei laden */
$docDatei = Dom\HTMLDocument::createFromFile('seite.html');
Die wichtigsten Unterschiede zur klassischen Klasse sind die statischen Factory-Methoden createFromString() und createFromFile() anstelle von loadHTML() und loadHTMLFile(). Der HTML5-Parser verarbeitet auch selbstschließende Tags, template-Elemente und andere HTML5-spezifische Konstrukte korrekt, die mit dem alten Parser Probleme verursacht hätten. Außerdem werden UTF-8-Inhalte standardmäßig korrekt behandelt, sodass der Workaround mit dem vorangestellten Meta-Tag entfällt.
Für neue Projekte, die PHP 8.4 oder höher voraussetzen, empfiehlt sich der Umstieg auf Dom\HTMLDocument. Die neue Klasse befindet sich im Namespace Dom und ist nicht abwärtskompatibel zur klassischen DOMDocument-Klasse. Das bedeutet, dass bestehender Code angepasst werden muss, wenn er auf die neue API umgestellt wird. Für ältere Projekte bleibt DOMDocument weiterhin verfügbar und voll funktionsfähig. Beide Klassen können innerhalb desselben Projekts parallel verwendet werden.
Fazit
Die Klasse DOMDocument ist das zentrale Werkzeug in PHP, um HTML und XML programmatisch zu laden, zu durchsuchen und zu manipulieren. Mit loadHTML() und loadXML() werden Dokumente aus Strings oder Dateien geparst. Dabei sollte stets libxml_use_internal_errors(true) vor dem Laden aufgerufen werden, um unerwünschte Warnungen bei fehlerhaftem HTML zu unterbinden. Die Methoden getElementsByTagName() und getElementById() ermöglichen einfache Suchvorgänge, während DOMXPath komplexe Abfragen mit voller XPath-Syntax unterstützt. Neue Elemente werden mit createElement() erzeugt und über appendChild() in den Baum eingefügt. Die UTF-8-Problematik lässt sich durch ein vorangestelltes <meta charset="utf-8">-Tag zuverlässig lösen. Ab PHP 8.4 steht mit Dom\HTMLDocument eine modernisierte Alternative bereit, die einen standardkonformen HTML5-Parser mitbringt und viele bekannte Einschränkungen des klassischen DOMDocument behebt. Wer heute mit PHP HTML oder XML verarbeiten möchte, findet in DOMDocument eine bewährte und gut dokumentierte Lösung, die nahezu alle Anforderungen an das Parsen und Manipulieren von Dokumentstrukturen abdeckt.
