Dom\Document — Klasse · PHP-Referenz

Signatur

class Dom\Document extends Dom\Node implements Dom\ParentNode

Beschreibung

Dom\Document ist die zentrale Klasse des modernen PHP-DOM-APIs (eingeführt in PHP 8.4) und repräsentiert ein gesamtes HTML- oder XML-Dokument. Sie bildet die Wurzel des Dokumentbaums und dient als Fabrik für alle anderen DOM-Knoten wie Elemente, Textknoten oder Attribute. Im Gegensatz zur älteren DOMDocument-Klasse folgt Dom\Document dem modernen WHATWG-DOM-Standard und bietet eine sauberere, konsistentere API.

Über Dom\Document können Dokumente geparst (createFromString(), createFromFile()), traversiert und manipuliert werden. Das Dokument agiert als Einstiegspunkt für alle Knotenoperationen: Neue Knoten werden stets über die Dokumentinstanz erstellt und anschließend in den Baum eingefügt. Abfragen lassen sich komfortabel per querySelector() und querySelectorAll() durchführen.

Die Klasse unterscheidet zwischen HTML- und XML-Dokumenten: Für HTML-Dokumente sollte Dom\HTMLDocument verwendet werden, während Dom\XMLDocument für reine XML-Anwendungsfälle vorgesehen ist. Dom\Document selbst ist die gemeinsame Basisklasse beider spezialisierter Varianten.

Ein wesentlicher Vorteil gegenüber DOMDocument ist die strikte Typbehandlung: Methoden werfen Dom\DOMException statt Fehler zu unterdrücken, und Rückgabewerte sind präziser typisiert, was die Fehlersuche erheblich erleichtert.

Beispiele

HTML-Dokument parsen und Element abfragen

<?php
// Dom\HTMLDocument erbt von Dom\Document und ist für HTML gedacht
$doc = Dom\HTMLDocument::createFromString(
    '<html><body><h1 id="title">Hallo Welt</h1><p class="intro">Willkommen.</p></body></html>',
    LIBXML_NOERROR
);

// Element per ID abfragen
$heading = $doc->getElementById('title');
echo $heading->textContent . PHP_EOL;

// CSS-Selektor verwenden
$intro = $doc->querySelector('.intro');
echo $intro->textContent . PHP_EOL;

Hallo Welt Willkommen.

XML-Dokument erstellen und manipulieren

<?php
// Dom\XMLDocument erbt von Dom\Document und ist für XML gedacht
$doc = Dom\XMLDocument::createFromString(
    '<?xml version="1.0" encoding="UTF-8"?><root><item>Eins</item></root>'
);

// Neues Element erstellen und anhängen
$newItem = $doc->createElement('item');
$newItem->textContent = 'Zwei';
$doc->documentElement->appendChild($newItem);

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

// Dokument als XML-String ausgeben
echo $doc->saveXml();

Eins Zwei <?xml version="1.0" encoding="UTF-8"?> <root><item>Eins</item><item>Zwei</item></root>

Dokument aus Datei laden und Knoten traversieren

<?php
// XML aus einer Datei laden
try {
    $doc = Dom\XMLDocument::createFromFile('/pfad/zur/datei.xml');
    $root = $doc->documentElement;
    echo 'Wurzelelement: ' . $root->nodeName . PHP_EOL;
    echo 'Kinder: ' . $root->childElementCount . PHP_EOL;
} catch (Dom\DOMException $e) {
    echo 'Fehler beim Laden: ' . $e->getMessage();
}

// Wichtig · Fallstricke

Neu in PHP 8.4: Der Dom\-Namespace wurde in PHP 8.4 eingeführt. Für ältere PHP-Versionen muss die klassische DOMDocument-Klasse verwendet werden.

Instanziierung: Dom\Document selbst wird typischerweise nicht direkt instanziiert. Stattdessen verwendet man die statischen Fabrikmethoden Dom\HTMLDocument::createFromString(), Dom\HTMLDocument::createFromFile(), Dom\XMLDocument::createFromString() oder Dom\XMLDocument::createFromFile().

Fehlerbehandlung: Im Gegensatz zu DOMDocument wirft Dom\Document bei Fehlern Dom\DOMException-Ausnahmen, anstatt false zurückzugeben oder PHP-Warnungen auszulösen. Parseoperationen sollten daher in try/catch-Blöcke eingebettet werden.

Sicherheit: Beim Parsen von extern geliefertem HTML oder XML sollte LIBXML_NONET verwendet werden, um externe Entitäten und DTD-Netzwerkzugriffe zu verhindern (XXE-Angriffe). Ebenso ist auf die korrekte Kodierung von Ausgaben zu achten, um XSS zu vermeiden.

Siehe auch

Dom\HTMLDocument Dom\XMLDocument Dom\Node Dom\Element Dom\ParentNode Dom\DOMException DOMDocument