libxml_clear_errors()

Die Funktion libxml_clear_errors() in PHP leert den internen Fehlerpuffer, der von libxml-basierten Erweiterungen wie DOMDocument, SimpleXML und XMLReader befüllt wird. Diese Seite erklärt, wann libxml Fehler sammelt, warum Sie diese löschen müssen und wie Sie libxml_clear_errors() mit den anderen Funktionen der libxml-Fehler-API kombinieren.

Syntax

libxml_clear_errors(): void

Die Funktion nimmt keine Argumente entgegen und gibt keinen Wert zurück (void). Sie ist seit PHP 5.1.0 verfügbar und funktioniert in jeder modernen PHP-Version.

Warum Sie libxml-Fehler löschen müssen

Standardmäßig gibt libxml Parsing-Fehler als PHP-Warnungen aus. Um diese stattdessen im eigenen Code zu behandeln, rufen Sie libxml_use_internal_errors(true) auf. Ab diesem Punkt hört libxml auf, Warnungen auszugeben, und fügt jeden Fehler stillschweigend einem internen Puffer hinzu.

Dieser Puffer ist global und für die gesamte Anfrage persistent: Er wächst mit jeder Verarbeitung oder Validierung, die Sie durchführen. Wenn Sie in einem Skript mehrere Dokumente verarbeiten — oder einen langlebigen Worker betreiben — verbleiben veraltete Fehler eines früheren Dokuments im Puffer und können die Ergebnisse von libxml_get_errors() und libxml_get_last_error() später verfälschen.

libxml_clear_errors() leert diesen Puffer und gibt Ihnen vor der nächsten Operation einen sauberen Ausgangszustand.

Verwendung von libxml_clear_errors()

Der typische Ablauf ist:

1. Aktivieren Sie die interne Fehlerbehandlung mit libxml_use_internal_errors(true).
2. Parsen oder validieren Sie ein Dokument.
3. Lesen Sie die gesammelten Fehler mit libxml_get_errors() (oder libxml_get_last_error()).
4. Rufen Sie libxml_clear_errors() auf, um den Puffer vor dem nächsten Dokument zurückzusetzen.

Hier ist ein eigenständiges, ausführbares Beispiel, das ungültiges XML aus einem String lädt, die Fehler untersucht und diese anschließend löscht:

<?php
// 1. Capture libxml errors in the internal buffer instead of emitting warnings.
libxml_use_internal_errors(true);

// Intentionally malformed XML: <title> is closed by </book>, not </title>.
$xml = '<book><title>PHP</book>';

$doc = new DOMDocument();
$doc->loadXML($xml);

// 2. Inspect the errors that were collected.
$errors = libxml_get_errors();
echo "Errors before clearing: " . count($errors) . "\n";
echo "First message: " . trim($errors[0]->message) . "\n";

// 3. Clear the buffer.
libxml_clear_errors();

// 4. The buffer is now empty.
echo "Errors after clearing: " . count(libxml_get_errors()) . "\n";

Dies gibt aus:

Errors before clearing: 2
First message: Opening and ending tag mismatch: title line 1 and book
Errors after clearing: 0

Validierung gegen ein Schema

libxml_clear_errors() ist besonders nützlich, wenn Sie Dokumente in einer Schleife verarbeiten. Nach jeder Validierung lesen Sie das Ergebnis und leeren dann den Puffer, damit das nächste Dokument frisch startet:

<?php
libxml_use_internal_errors(true);

$documents = ['a.xml', 'b.xml', 'c.xml'];

foreach ($documents as $file) {
    $doc = new DOMDocument();
    $doc->load($file);

    if ($doc->schemaValidate('schema.xsd')) {
        echo "$file is valid\n";
    } else {
        // Only the errors for THIS document, because we clear after each one.
        foreach (libxml_get_errors() as $error) {
            echo "$file: " . trim($error->message) . "\n";
        }
    }

    // Reset the buffer before validating the next file.
    libxml_clear_errors();
}

Ohne den Aufruf von libxml_clear_errors() am Ende jeder Iteration würden Fehler aus a.xml noch erscheinen, wenn Sie Fehler für b.xml ausgeben.

Häufige Fallstricke

• Das Löschen deaktiviert nicht die Fehlersammlung. libxml_clear_errors() leert nur den Puffer; libxml sammelt weiterhin neue Fehler, solange libxml_use_internal_errors(true) aktiv ist.
• Es ist global. Der Puffer wird von DOMDocument, SimpleXML und XMLReader gemeinsam genutzt. Das Löschen betrifft alle drei.
• Die Reihenfolge ist wichtig. Lesen Sie Fehler mit libxml_get_errors() immer vor dem Löschen — einmal gelöscht, sind sie unwiederbringlich verloren.

Verwandte Funktionen

• libxml_use_internal_errors() — den internen Fehlerpuffer ein- oder ausschalten.
• libxml_get_errors() — alle aktuell im Puffer vorhandenen Fehler abrufen.
• libxml_get_last_error() — nur den zuletzt aufgetretenen Fehler abrufen.

Fazit

Die Funktion libxml_clear_errors() bietet eine unkomplizierte Möglichkeit, den internen Fehlerpuffer von libxml zu verwalten. Durch das Zurücksetzen des Puffers nach Operationen wie DOMDocument::load() oder DOMDocument::schemaValidate() verhindern Sie, dass veraltete Fehler in spätere Ergebnisse einfließen — was besonders in Schleifen und langlebigen Skripten wichtig ist.

Übungen