libxml_use_internal_errors()

La fonction libxml_use_internal_errors() permet d'indiquer aux extensions PHP basées sur libxml (DOM, SimpleXML, XMLReader, XMLWriter) de ne plus afficher les avertissements à l'écran, mais de les collecter dans un tampon interne que vous pouvez inspecter depuis votre propre code.

Cette page explique ce que fait la fonction, sa signature et sa valeur de retour, ainsi que la façon de la combiner avec le reste de l'API d'erreurs libxml pour analyser du XML malformé de manière robuste.

Pourquoi utiliser la gestion interne des erreurs ?

Par défaut, lorsque libxml rencontre du XML malformé, il génère des avertissements PHP. Dans une application web, ces avertissements encombrent soit votre sortie, soit sont silencieusement ignorés selon vos paramètres display_errors/error_reporting — et vous n'avez aucun moyen structuré d'y réagir.

Appeler libxml_use_internal_errors(true) change cela :

• L'analyse n'émet plus d'avertissements PHP. Votre script continue de s'exécuter.
• Chaque problème est ajouté à un tampon interne sous la forme d'un objet LibXMLError.
• Vous décidez de ce qu'il faut faire — le journaliser, afficher un message convivial, interrompre l'exécution ou ignorer les problèmes non fatals.

Il s'agit du modèle standard pour analyser du XML que vous ne contrôlez pas (téléversements d'utilisateurs, flux tiers, HTML extrait).

Syntaxe

libxml_use_internal_errors(?bool $use_errors = null): bool

• $use_errors — passez true pour activer la gestion interne des erreurs, false pour la désactiver. Passez null (ou omettez l'argument) pour interroger l'état actuel sans le modifier.
• Valeur de retour — la fonction retourne le paramètre précédent (un bool). Cela vous permet de restaurer l'ancien état une fois terminé, afin de ne pas affecter le code non lié.

Comment utiliser libxml_use_internal_errors()

Activez les erreurs internes, analysez le document, puis lisez le tampon avec libxml_get_errors() et videz-le avec libxml_clear_errors().

L'exemple ci-dessous analyse du XML malformé en ligne (aucun fichier externe n'est nécessaire, vous pouvez donc l'exécuter tel quel) :

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

Sortie :

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

Notez qu'aucun avertissement PHP n'a été affiché — le document malformé a produit deux objets d'erreur structurés à la place.

Lire un objet LibXMLError

Chaque élément retourné par libxml_get_errors() (ou libxml_get_last_error()) est un objet LibXMLError avec des champs utiles :

Vous pouvez utiliser level pour ignorer les avertissements inoffensifs tout en échouant sur les erreurs fatales :

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

Sortie :

Fatal parse error (code 77)

Restaurer l'état précédent

Étant donné que la fonction retourne le paramètre précédent, une bibliothèque qui active les erreurs internes devrait les rétablir ensuite afin de ne pas modifier le comportement du reste de l'application :

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

Pièges courants

• Le tampon est global et persistant. Les erreurs s'accumulent jusqu'à ce que vous appeliez libxml_clear_errors() (ou que la requête se termine). Videz-le toujours entre les analyses, sinon vous relirez des erreurs obsolètes.
• Cela affecte également le chargement HTML. DOMDocument::loadHTML() signale le balisage invalide via le même mécanisme — pratique pour extraire du HTML imparfait sans avertissements.
• Désactiver réactive les avertissements PHP. Appeler libxml_use_internal_errors(false) remet libxml dans son comportement par défaut d'émission d'avertissements/notices.

Conclusion

libxml_use_internal_errors() est la porte d'entrée vers une gestion robuste du XML en PHP : activez-la pour faire taire les avertissements par défaut de libxml, puis utilisez libxml_get_errors(), libxml_get_last_error() et libxml_clear_errors() pour inspecter et gérer les problèmes selon vos propres conditions. N'oubliez pas sa valeur de retour pour pouvoir restaurer l'état précédent, et videz toujours le tampon entre les analyses.

Pratique