DOMException — Klasse · PHP-Referenz

Signatur

class DOMException extends RuntimeException

Beschreibung

DOMException ist die Ausnahme-Klasse, die von der PHP-DOM-Erweiterung verwendet wird, um Fehler zu signalisieren, die dem W3C-DOM-Standard entsprechen. Sie erweitert RuntimeException und enthält zusätzlich einen standardisierten Fehlercode, der dem jeweiligen DOM-Fehlertyp entspricht (z. B. DOM_INVALID_CHARACTER_ERR, DOM_NOT_FOUND_ERR etc.).

Typische Situationen, in denen eine DOMException geworfen wird, sind: Einfügen eines Knotens in einen falschen Elternknoten, Verwendung ungültiger Zeichen in Element- oder Attributnamen, oder der Versuch, einen Knoten aus einem anderen Dokument einzufügen, ohne ihn vorher zu importieren.

Da DOMException von RuntimeException erbt, können Instanzen mit einem gewöhnlichen try/catch-Block abgefangen werden. Der Fehlercode (getCode()) entspricht einer der vordefinierten DOM-Fehlerkonstanten und erlaubt eine präzise Unterscheidung der Fehlerursache.

Wichtig: Nicht alle DOM-Methoden werfen bei Fehlern eine Exception – ältere PHP-Versionen gaben in manchen Fällen lediglich Warnungen aus. Seit PHP 8.0 ist das Verhalten konsistenter, und viele Operationen werfen nun zuverlässig eine DOMException.

Beispiele

DOMException beim Erzeugen eines Elements mit ungültigem Namen abfangen

<?php
$doc = new DOMDocument();

try {
    // Ein Leerzeichen im Element-Namen ist laut DOM-Standard ungültig
    $element = $doc->createElement('invalid name');
} catch (DOMException $e) {
    echo 'DOM-Fehler (Code ' . $e->getCode() . '): ' . $e->getMessage();
}

DOM-Fehler (Code 5): Invalid Character Error

DOMException beim Einfügen eines Knotens aus fremdem Dokument

<?php
$doc1 = new DOMDocument();
$root1 = $doc1->createElement('root');
$doc1->appendChild($root1);

$doc2 = new DOMDocument();
$root2 = $doc2->createElement('other');
$doc2->appendChild($root2);

try {
    // Knoten aus doc2 kann nicht direkt in doc1 eingefügt werden
    $doc1->documentElement->appendChild($root2);
} catch (DOMException $e) {
    echo 'Fehler: ' . $e->getMessage() . PHP_EOL;
    echo 'Code: ' . $e->getCode() . PHP_EOL;

    // Korrekte Lösung: Knoten importieren
    $imported = $doc1->importNode($root2, true);
    $doc1->documentElement->appendChild($imported);
    echo $doc1->saveXML();
}

Fehler: Wrong Document Error Code: 4 <?xml version="1.0"?> <root><other/></root>

// Wichtig · Fallstricke

Fehlercodes: Der von getCode() zurückgegebene Wert entspricht den W3C-DOM-Fehlerkonstanten. Die wichtigsten sind:

1 – DOM_INDEX_SIZE_ERR: Index außerhalb des gültigen Bereichs.
3 – DOM_HIERARCHY_REQUEST_ERR: Ungültige Einfüge-Hierarchie.
4 – DOM_WRONG_DOCUMENT_ERR: Knoten gehört zu einem anderen Dokument.
5 – DOM_INVALID_CHARACTER_ERR: Ungültiges Zeichen im Namen.
8 – DOM_NOT_FOUND_ERR: Knoten nicht gefunden.
9 – DOM_NOT_SUPPORTED_ERR: Operation nicht unterstützt.

In PHP vor 8.0 wurden einige DOM-Fehler als PHP-Warnungen ausgegeben, statt als DOMException. Wer Abwärtskompatibilität benötigt, sollte zusätzlich einen Error-Handler einsetzen.

Siehe auch

DOMDocument DOMNode RuntimeException DOMNode::appendChild DOMDocument::importNode