libxml_use_internal_errors()

La funzione libxml_use_internal_errors() consente di indicare alle estensioni PHP basate su libxml (DOM, SimpleXML, XMLReader, XMLWriter) di non stampare avvisi sullo schermo e di raccoglierli invece in un buffer interno che è possibile esaminare dal proprio codice.

Questa pagina spiega cosa fa la funzione, la sua firma e il valore restituito, e come combinarla con il resto dell'API degli errori libxml per analizzare XML problematico in modo controllato.

Perché usare la gestione interna degli errori?

Per impostazione predefinita, quando libxml incontra XML non valido genera warning PHP. In un'applicazione web questi warning o sporcano l'output o vengono inghiottiti silenziosamente a seconda delle impostazioni di display_errors/error_reporting — e non si ha un modo strutturato per gestirli.

Chiamare libxml_use_internal_errors(true) cambia questo comportamento:

• Il parsing non emette più warning PHP. Lo script continua a essere eseguito.
• Ogni problema viene inserito in un buffer interno come oggetto LibXMLError.
• Si decide cosa fare — registrarlo, mostrare un messaggio all'utente, interrompere l'esecuzione o ignorare i problemi non critici.

Questo è il pattern standard per analizzare XML che non si controlla (upload degli utenti, feed di terze parti, HTML estratto da siti web).

Sintassi

libxml_use_internal_errors(?bool $use_errors = null): bool

• $use_errors — passare true per abilitare la gestione interna degli errori, false per disabilitarla. Passare null (o omettere l'argomento) per interrogare lo stato corrente senza modificarlo.
• Valore restituito — la funzione restituisce l'impostazione precedente (un bool). Questo consente di ripristinare il vecchio stato al termine, evitando di influenzare codice non correlato.

Come usare libxml_use_internal_errors()

Abilitare gli errori interni, analizzare il documento, quindi leggere il buffer con libxml_get_errors() e svuotarlo con libxml_clear_errors().

L'esempio seguente analizza XML non valido inline (senza file esterni, quindi può essere eseguito così com'è):

<?php
// 1. Route libxml warnings into the internal buffer.
libxml_use_internal_errors(true);

// 2. Deliberately broken XML: <from> is never closed.
$xml = <<<XML
<?xml version="1.0"?>
<note>
  <to>Tove</to>
  <from>Jani
</note>
XML;

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

// 3. Inspect what went wrong.
foreach (libxml_get_errors() as $error) {
    echo trim($error->message) . " (line {$error->line})\n";
}

// 4. Empty the buffer so later parses start clean.
libxml_clear_errors();
?>

Output:

Opening and ending tag mismatch: from line 4 and note (line 5)
Premature end of data in tag note line 2 (line 5)

Si noti che non è stato stampato alcun warning PHP — il documento non valido ha prodotto due oggetti di errore strutturati.

Lettura di un oggetto LibXMLError

Ogni elemento restituito da libxml_get_errors() (o da libxml_get_last_error()) è un oggetto LibXMLError con campi utili:

È possibile usare level per ignorare i warning non critici continuando a segnalare gli errori fatali:

<?php
libxml_use_internal_errors(true);

$doc = new DOMDocument();
$doc->loadXML('<a><b></a>'); // mismatched tags → fatal

$error = libxml_get_last_error();

if ($error && $error->level === LIBXML_ERR_FATAL) {
    echo "Fatal parse error (code {$error->code})\n";
}
?>

Output:

Fatal parse error (code 77)

Ripristinare lo stato precedente

Poiché la funzione restituisce l'impostazione precedente, una libreria che abilita la gestione interna degli errori dovrebbe ripristinarla al termine, per non alterare il comportamento del resto dell'applicazione:

<?php
$previous = libxml_use_internal_errors(true);

// ... parse XML and handle libxml_get_errors() ...

libxml_clear_errors();
libxml_use_internal_errors($previous); // restore whatever the caller had
?>

Errori comuni

• Il buffer è globale e persistente. Gli errori si accumulano finché non si chiama libxml_clear_errors() (o fino alla fine della richiesta). Svuotarlo sempre tra un'analisi e l'altra, altrimenti si rileggeranno errori obsoleti.
• Interessa anche il caricamento HTML. DOMDocument::loadHTML() segnala il markup non valido attraverso lo stesso meccanismo — utile per fare scraping di HTML imperfetto senza generare warning.
• Disabilitarlo riattiva i warning PHP. Chiamare libxml_use_internal_errors(false) riporta libxml al comportamento predefinito di emissione di warning/notice.

Conclusione

libxml_use_internal_errors() è il punto di ingresso per una gestione robusta dell'XML in PHP: abilitarla per silenziare i warning predefiniti di libxml, quindi usare libxml_get_errors(), libxml_get_last_error() e libxml_clear_errors() per esaminare e gestire i problemi secondo le proprie esigenze. Ricordare il valore restituito per poter ripristinare lo stato precedente e svuotare sempre il buffer tra un'analisi e l'altra.

Pratica