libxml_get_last_error()

La funzione libxml_get_last_error() in PHP recupera l'ultimo errore generato dalla libreria libxml — il parser che alimenta le estensioni DOMDocument, SimpleXML e XMLReader di PHP. Quando si analizza o si valida XML non corretto, libxml registra cosa è andato storto; questa funzione consente di leggere il record più recente per mostrare un messaggio utile invece di un avviso criptico.

Questa pagina descrive cosa restituisce la funzione, come acquisire gli errori con libxml_use_internal_errors(), le proprietà dell'oggetto errore e quando utilizzare libxml_get_last_error() rispetto alle funzioni correlate.

Sintassi

libxml_get_last_error(): LibXMLError|false

La funzione non accetta argomenti. Restituisce:

• Un oggetto LibXMLError che descrive l'errore più recente, oppure
• false se non è stato registrato alcun errore dall'ultima chiamata a libxml_clear_errors().

Perché è necessaria

Per impostazione predefinita, libxml emette gli errori come avvisi PHP, che ingombrano l'output e sono difficili da gestire a livello di codice. Il pattern tipico è:

1. Chiamare libxml_use_internal_errors(true) per sopprimere gli avvisi e memorizzare gli errori in un buffer interno.
2. Analizzare o validare il proprio XML.
3. Leggere il buffer con libxml_get_last_error() (solo il più recente) o libxml_get_errors() (tutti).
4. Svuotare il buffer con libxml_clear_errors() in modo che l'operazione successiva parta pulita.

Utilizzare libxml_get_last_error() quando si è interessati solo a cosa ha appena fallito — ad esempio, per segnalare perché una singola chiamata di parsing non è riuscita.

L'oggetto LibXMLError

L'oggetto restituito espone le seguenti proprietà pubbliche:

Esempio: rilevare un errore di parsing

Questo esempio analizza una stringa XML intenzionalmente non corretta (un tag di chiusura mancante), quindi stampa l'errore acquisito. È completamente autonomo — non è necessario alcun file esterno:

<?php
// Store libxml errors in an internal buffer instead of emitting warnings
libxml_use_internal_errors(true);

// This XML is malformed: <title> is never closed
$badXml = '<book><title>PHP</book>';

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

$error = libxml_get_last_error();

if ($error !== false) {
    echo "Error level:  " . $error->level   . PHP_EOL;
    echo "Error code:   " . $error->code    . PHP_EOL;
    echo "Line:         " . $error->line     . PHP_EOL;
    echo "Message:      " . trim($error->message) . PHP_EOL;
} else {
    echo "The XML parsed without errors." . PHP_EOL;
}

// Always clear the buffer when you are done with it
libxml_clear_errors();
?>

Output:

Error level:  3
Line:         1
Message:      Premature end of data in tag book line 1

Il code, il column e il testo del messaggio esatti dipendono dalla versione di libxml in uso, ma la struttura è sempre la stessa. level è 3 (LIBXML_ERR_FATAL) perché il tag non chiuso rende il documento non analizzabile. (code è omesso dall'output sopra solo perché il suo valore è specifico della versione.)

Esempio: validazione rispetto a uno schema

Un utilizzo comune nel mondo reale è segnalare perché un documento ha fallito la validazione dello schema:

<?php
libxml_use_internal_errors(true);

$doc = new DOMDocument();
$doc->load('example.xml');

if ($doc->schemaValidate('example.xsd')) {
    echo "The XML document is valid.";
} else {
    $error = libxml_get_last_error();
    if ($error !== false) {
        echo "Validation failed: " . trim($error->message);
    }
}

libxml_clear_errors();
?>

Qui si controlla il valore restituito da libxml_get_last_error() rispetto a false prima di accedere a $error->message — accedere a una proprietà su false genererebbe un proprio avviso.

Errori comuni da evitare

• È necessario abilitare prima la gestione interna degli errori. Senza libxml_use_internal_errors(true), libxml stampa avvisi e il buffer interno rimane vuoto, quindi libxml_get_last_error() restituisce false.
• Svuotare il buffer tra un'operazione e l'altra. Gli errori si accumulano. Se non si chiama libxml_clear_errors(), una chiamata successiva a libxml_get_last_error() potrebbe restituire un errore obsoleto di un parsing precedente.
• "Ultimo" significa ultimo, non "questa chiamata". La funzione restituisce ciò che si trova alla fine del buffer, indipendentemente da quale parsing lo ha prodotto.

Funzioni correlate

• libxml_get_errors() — restituisce un array di tutti gli errori nel buffer, non solo il più recente.
• libxml_clear_errors() — svuota il buffer degli errori.
• libxml_use_internal_errors() — attiva o disattiva se gli errori vengono memorizzati nel buffer o emessi come avvisi.

Per un contesto più ampio sul parsing XML in PHP, vedere The XML DOM in PHP e SimpleXML.

Conclusione

libxml_get_last_error() fornisce accesso programmatico all'errore di parsing o validazione XML più recente, trasformando i fallimenti silenziosi e gli avvisi rumorosi in messaggi utili. Abbinarla a libxml_use_internal_errors() per acquisire gli errori e a libxml_clear_errors() per reimpostare il buffer, e utilizzare libxml_get_errors() quando si ha bisogno dell'elenco completo anziché solo dell'ultimo.

Pratica