libxml_clear_errors()

La fonction libxml_clear_errors() en PHP vide le tampon d'erreurs interne rempli par les extensions basées sur libxml, telles que DOMDocument, SimpleXML et XMLReader. Cette page explique quand libxml collecte les erreurs, pourquoi vous devez les effacer, et comment combiner libxml_clear_errors() avec les autres fonctions de l'API d'erreurs libxml.

Syntaxe

libxml_clear_errors(): void

La fonction ne prend aucun argument et ne retourne aucune valeur (void). Elle est disponible depuis PHP 5.1.0 et fonctionne avec toutes les versions modernes de PHP.

Pourquoi vider les erreurs libxml

Par défaut, libxml émet les erreurs d'analyse comme des avertissements PHP. Pour les gérer dans votre propre code à la place, vous appelez libxml_use_internal_errors(true). À partir de ce moment, libxml cesse d'afficher les avertissements et ajoute silencieusement chaque erreur à un tampon interne.

Ce tampon est global et persistant pour la requête : il continue de grossir à chaque analyse ou validation que vous effectuez. Si vous traitez plusieurs documents dans un seul script — ou si vous exécutez un processus de longue durée — les erreurs obsolètes d'un document précédent restent dans le tampon et peuvent polluer les résultats de libxml_get_errors() et libxml_get_last_error() ultérieurement.

libxml_clear_errors() vide ce tampon, vous donnant une ardoise vierge avant la prochaine opération.

Comment utiliser libxml_clear_errors()

Le flux typique est le suivant :

1. Activez la gestion interne des erreurs avec libxml_use_internal_errors(true).
2. Analysez ou validez un document.
3. Lisez les erreurs collectées avec libxml_get_errors() (ou libxml_get_last_error()).
4. Appelez libxml_clear_errors() pour réinitialiser le tampon avant le prochain document.

Voici un exemple autonome et exécutable qui charge du XML invalide depuis une chaîne, inspecte les erreurs, puis les efface :

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

Ce code affiche :

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

Validation par rapport à un schéma

libxml_clear_errors() est particulièrement utile lorsque vous traitez des documents dans une boucle. Après chaque validation, vous lisez le résultat, puis videz le tampon afin que le document suivant commence avec un état propre :

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

Sans l'appel à libxml_clear_errors() à la fin de chaque itération, les erreurs de a.xml apparaîtraient encore lors du rapport des erreurs pour b.xml.

Pièges courants

• Vider le tampon ne désactive pas la collecte des erreurs. libxml_clear_errors() vide uniquement le tampon ; libxml continue de collecter de nouvelles erreurs tant que libxml_use_internal_errors(true) est actif.
• Il est global. Le tampon est partagé entre DOMDocument, SimpleXML et XMLReader. Le vider affecte tous ces composants.
• L'ordre est important. Lisez toujours les erreurs avec libxml_get_errors() avant de les effacer — une fois vidées, elles sont perdues.

Fonctions associées

• libxml_use_internal_errors() — activer ou désactiver le tampon d'erreurs interne.
• libxml_get_errors() — récupérer toutes les erreurs actuellement dans le tampon.
• libxml_get_last_error() — récupérer uniquement l'erreur la plus récente.

Conclusion

La fonction libxml_clear_errors() offre un moyen simple de gérer le tampon d'erreurs interne de libxml. En réinitialisant le tampon après des opérations comme DOMDocument::load() ou DOMDocument::schemaValidate(), vous évitez que des erreurs obsolètes ne se glissent dans les résultats ultérieurs — ce qui est particulièrement important dans les boucles et les scripts de longue durée.

Pratique