libxml_clear_errors()

La función libxml_clear_errors() en PHP vacía el búfer interno de errores que rellenan las extensiones basadas en libxml, como DOMDocument, SimpleXML y XMLReader. Esta página explica cuándo libxml recopila errores, por qué es necesario borrarlos y cómo combinar libxml_clear_errors() con las demás funciones de la API de errores de libxml.

Sintaxis

libxml_clear_errors(): void

La función no recibe argumentos y no devuelve ningún valor (void). Está disponible desde PHP 5.1.0 y funciona en todas las versiones modernas de PHP.

Por qué necesitas borrar los errores de libxml

De forma predeterminada, libxml emite los errores de análisis como advertencias de PHP. Para gestionarlos en tu propio código, debes llamar a libxml_use_internal_errors(true). A partir de ese momento, libxml deja de mostrar advertencias y añade silenciosamente cada error a un búfer interno.

Ese búfer es global y persiste durante toda la solicitud: crece con cada análisis o validación que se ejecute. Si procesas varios documentos en un mismo script —o ejecutas un worker de larga duración— los errores de un documento anterior permanecen en el búfer y pueden contaminar los resultados de libxml_get_errors() y libxml_get_last_error() en operaciones posteriores.

libxml_clear_errors() vacía ese búfer, proporcionando un estado limpio antes de la siguiente operación.

Cómo usar libxml_clear_errors()

El flujo típico es:

1. Activar el manejo interno de errores con libxml_use_internal_errors(true).
2. Analizar o validar un documento.
3. Leer los errores recopilados con libxml_get_errors() (o libxml_get_last_error()).
4. Llamar a libxml_clear_errors() para reiniciar el búfer antes del siguiente documento.

A continuación se muestra un ejemplo completo y ejecutable que carga XML no válido desde una cadena, inspecciona los errores y luego los borra:

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

Esto imprime:

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

Validación con un esquema

libxml_clear_errors() resulta más útil cuando se procesan documentos en un bucle. Tras cada validación se lee el resultado y luego se borra el búfer para que el siguiente documento comience desde cero:

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

Sin la llamada a libxml_clear_errors() al final de cada iteración, los errores de a.xml seguirían apareciendo al notificar los errores de b.xml.

Errores comunes

• Borrar el búfer no deshabilita la recopilación de errores. libxml_clear_errors() solo vacía el búfer; libxml sigue recopilando nuevos errores mientras libxml_use_internal_errors(true) esté activo.
• Es global. El búfer se comparte entre DOMDocument, SimpleXML y XMLReader. Borrarlo afecta a todos ellos.
• El orden importa. Siempre lee los errores con libxml_get_errors() antes de borrarlos — una vez borrados, desaparecen para siempre.

Funciones relacionadas

• libxml_use_internal_errors() — activa o desactiva el búfer interno de errores.
• libxml_get_errors() — obtiene todos los errores que hay actualmente en el búfer.
• libxml_get_last_error() — obtiene únicamente el error más reciente.

Conclusión

La función libxml_clear_errors() ofrece una manera sencilla de gestionar el búfer interno de errores de libxml. Al reiniciar el búfer después de operaciones como DOMDocument::load() o DOMDocument::schemaValidate(), se evita que los errores obsoletos contaminen resultados posteriores — algo especialmente importante en bucles y scripts de larga duración.

Práctica