libxml_clear_errors()

La funzione libxml_clear_errors() in PHP svuota il buffer interno degli errori popolato dalle estensioni basate su libxml come DOMDocument, SimpleXML e XMLReader. Questa pagina spiega quando libxml raccoglie gli errori, perché è necessario eliminarli e come combinare libxml_clear_errors() con le altre funzioni dell'API degli errori di libxml.

Sintassi

libxml_clear_errors(): void

La funzione non accetta argomenti e non restituisce alcun valore (void). È disponibile dalla versione PHP 5.1.0 e funziona in ogni versione moderna di PHP.

Perché è necessario eliminare gli errori di libxml

Per impostazione predefinita, libxml emette gli errori di parsing come avvisi PHP. Per gestirli nel proprio codice, si chiama libxml_use_internal_errors(true). Da quel momento in poi, libxml smette di stampare gli avvisi e aggiunge silenziosamente ogni errore a un buffer interno.

Quel buffer è globale e persistente per la richiesta: continua a crescere ad ogni parsing o validazione eseguita. Se si elaborano più documenti in uno script — o si esegue un worker a lunga esecuzione — gli errori obsoleti di un documento precedente rimangono nel buffer e possono inquinare i risultati di libxml_get_errors() e libxml_get_last_error() in seguito.

libxml_clear_errors() svuota quel buffer, fornendo una base pulita prima dell'operazione successiva.

Come usare libxml_clear_errors()

Il flusso tipico è:

1. Abilitare la gestione interna degli errori con libxml_use_internal_errors(true).
2. Effettuare il parsing o la validazione di un documento.
3. Leggere gli errori raccolti con libxml_get_errors() (o libxml_get_last_error()).
4. Chiamare libxml_clear_errors() per reimpostare il buffer prima del documento successivo.

Ecco un esempio autonomo ed eseguibile che carica un XML non valido da una stringa, esamina gli errori e poi li elimina:

<?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";

Questo stampa:

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

Validazione rispetto a uno schema

libxml_clear_errors() è più utile quando si elaborano documenti in un ciclo. Dopo ogni validazione si legge il risultato e poi si svuota il buffer in modo che il documento successivo parta da zero:

<?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();
}

Senza la chiamata a libxml_clear_errors() alla fine di ogni iterazione, gli errori di a.xml apparirebbero ancora quando si riportano gli errori di b.xml.

Errori comuni

• Eliminare non disabilita la raccolta degli errori. libxml_clear_errors() svuota solo il buffer; libxml continua a raccogliere nuovi errori finché libxml_use_internal_errors(true) è attivo.
• È globale. Il buffer è condiviso tra DOMDocument, SimpleXML e XMLReader. Svuotarlo influisce su tutti.
• L'ordine conta. Leggere sempre gli errori con libxml_get_errors() prima di eliminarli — una volta eliminati, sono persi.

Funzioni correlate

• libxml_use_internal_errors() — attiva o disattiva il buffer interno degli errori.
• libxml_get_errors() — recupera tutti gli errori attualmente nel buffer.
• libxml_get_last_error() — recupera solo l'errore più recente.

Conclusione

La funzione libxml_clear_errors() fornisce un modo diretto per gestire il buffer interno degli errori di libxml. Reimpostando il buffer dopo operazioni come DOMDocument::load() o DOMDocument::schemaValidate(), si evita che errori obsoleti si propaghino nei risultati successivi — il che è particolarmente importante nei cicli e negli script a lunga esecuzione.

Esercitazione