libxml_get_errors()

La funzione libxml_get_errors() in PHP recupera l'elenco di errori e avvisi generati dalle funzioni libxml — la libreria C che alimenta le estensioni DOMDocument, SimpleXML e XMLReader di PHP. Viene tipicamente chiamata dopo il parsing o la validazione di un documento XML per poter esaminare esattamente cosa è andato storto, invece di affidarsi agli avvisi di PHP.

Questa pagina tratta la firma della funzione, la struttura degli oggetti errore restituiti, un esempio eseguibile autonomo, come interpretare i livelli di severità degli errori e come si relaziona con le altre funzioni di gestione degli errori libxml.

Sintassi

libxml_get_errors(): array

Non accetta nessun argomento e restituisce un array di oggetti LibXMLError. Se non ci sono errori nel buffer, restituisce un array vuoto ([]).

Cosa restituisce libxml_get_errors()

Ogni elemento nell'array restituito è un oggetto LibXMLError con queste proprietà pubbliche:

Come usare libxml_get_errors()

C'è una regola da seguire obbligatoriamente: abilitare prima la gestione degli errori interna. Per impostazione predefinita, libxml scrive gli errori di parsing direttamente nell'output di PHP come avvisi, e il buffer degli errori rimane vuoto. Chiamare libxml_use_internal_errors(true) reindirizza quegli errori in un buffer interno che libxml_get_errors() può leggere.

Il flusso di lavoro tipico è:

1. Chiamare libxml_use_internal_errors(true) prima del parsing.
2. Analizzare o validare l'XML (con DOMDocument, SimpleXML, ecc.).
3. Chiamare libxml_get_errors() per leggere gli errori raccolti.
4. Chiamare libxml_clear_errors() per svuotare il buffer prima dell'operazione successiva.

Un esempio autonomo ed eseguibile

Questo esempio carica XML malformato da una stringa (senza file esterni) e stampa ogni errore con la sua severità, riga e colonna:

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

// Intentionally broken XML: <author> is never closed
$xml = <<<XML
<book>
  <title>PHP Basics</title>
  <author>Jane Doe
</book>
XML;

// 2. Parse it
$doc = new DOMDocument();
$doc->loadXML($xml);

// 3. Read the errors
$errors = libxml_get_errors();

// Map numeric levels to readable labels
$levels = [
    LIBXML_ERR_WARNING => 'Warning',
    LIBXML_ERR_ERROR   => 'Error',
    LIBXML_ERR_FATAL   => 'Fatal',
];

foreach ($errors as $error) {
    printf(
        "[%s] line %d, col %d: %s",
        $levels[$error->level] ?? 'Unknown',
        $error->line,
        $error->column,
        $error->message            // already ends with a newline
    );
}

// 4. Clear the buffer so it doesn't leak into later parsing
libxml_clear_errors();
?>

Output:

[Fatal] line 4, col 8: Opening and ending tag mismatch: author line 3 and book
[Fatal] line 4, col 8: Premature end of data in tag book line 1

Poiché il tag <author> viene lasciato aperto, libxml segnala due errori fatal, ognuno dei quali punta alla riga e alla colonna esatte in cui è stato rilevato il problema. Leggere level, line e column — anziché solo message — è ciò che rende libxml_get_errors() così utile per costruire feedback di validazione precisi.

Validazione rispetto a uno schema

Lo stesso schema funziona per la validazione tramite schema. Dopo che schemaValidate() / schemaValidateSource() restituisce false, gli errori di validazione si trovano nel buffer:

<?php
libxml_use_internal_errors(true);

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

// schemaValidateSource() validates against an in-memory XSD string
$xsd = file_get_contents('example.xsd');

if ($doc->schemaValidateSource($xsd)) {
    echo "The XML document is valid.\n";
} else {
    echo "The XML document is not valid:\n";
    foreach (libxml_get_errors() as $error) {
        echo trim($error->message) . "\n";
    }
}

libxml_clear_errors();
?>

Suggerimento: Se hai bisogno solo del singolo problema più recente, usa libxml_get_last_error() — restituisce un unico oggetto LibXMLError (o false) invece dell'intero array.

Insidie comuni

• Risultato vuoto? Quasi certamente hai dimenticato libxml_use_internal_errors(true). Senza di essa il buffer non viene mai popolato.
• Errori obsoleti. Il buffer è condiviso tra tutte le operazioni libxml nella richiesta. Chiama sempre libxml_clear_errors() dopo aver finito di gestire un batch, altrimenti gli errori precedenti riappariranno in una successiva chiamata a libxml_get_errors().
• Avvisi vs. errori fatali. Un array non vuoto non significa necessariamente che il documento sia inutilizzabile — filtra su $error->level >= LIBXML_ERR_ERROR se vuoi ignorare gli avvisi.

Funzioni correlate

• libxml_use_internal_errors() — attiva o disattiva il buffer degli errori.
• libxml_get_last_error() — recupera solo l'errore più recente.
• libxml_clear_errors() — svuota il buffer degli errori.
• Panoramica PHP libxml — l'estensione più ampia a cui appartengono queste funzioni.
• PHP XML DOM — parsing di documenti con DOMDocument.

Conclusione

La funzione libxml_get_errors() è uno strumento fondamentale per il debug delle operazioni XML in PHP. Abilitando la gestione degli errori interna con libxml_use_internal_errors(true), analizzando il documento e poi esaminando le proprietà level, line, column e message di ogni oggetto LibXMLError, puoi costruire una validazione XML precisa e intuitiva invece di ingoiare gli avvisi grezzi di PHP. Ricorda di svuotare il buffer con libxml_clear_errors() tra un'operazione e l'altra.

Pratica