libxml_clear_errors()

A função libxml_clear_errors() no PHP limpa o buffer interno de erros preenchido por extensões baseadas em libxml, como DOMDocument, SimpleXML e XMLReader. Esta página explica quando o libxml coleta erros, por que você precisa limpá-los e como combinar libxml_clear_errors() com as outras funções da API de erros do libxml.

Sintaxe

libxml_clear_errors(): void

A função não recebe argumentos e não retorna nenhum valor (void). Está disponível desde o PHP 5.1.0 e funciona em todas as versões modernas do PHP.

Por Que Você Precisa Limpar os Erros do libxml

Por padrão, o libxml emite erros de análise como avisos do PHP. Para tratá-los no seu próprio código, você chama libxml_use_internal_errors(true). A partir desse ponto, o libxml para de imprimir avisos e acrescenta silenciosamente cada erro a um buffer interno.

Esse buffer é global e persistente durante a requisição: ele continua crescendo a cada análise ou validação executada. Se você processar vários documentos em um único script — ou executar um worker de longa duração — erros antigos de um documento anterior permanecem no buffer e podem contaminar os resultados de libxml_get_errors() e libxml_get_last_error() mais tarde.

libxml_clear_errors() esvazia esse buffer, fornecendo um estado limpo antes da próxima operação.

Como Usar libxml_clear_errors()

O fluxo típico é:

1. Habilite o tratamento interno de erros com libxml_use_internal_errors(true).
2. Analise ou valide um documento.
3. Leia os erros coletados com libxml_get_errors() (ou libxml_get_last_error()).
4. Chame libxml_clear_errors() para redefinir o buffer antes do próximo documento.

Aqui está um exemplo completo e executável que carrega XML inválido de uma string, inspeciona os erros e depois os limpa:

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

Isso imprime:

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

Validando Contra um Schema

libxml_clear_errors() é mais útil quando você processa documentos em um loop. Após cada validação, você lê o resultado e limpa o buffer para que o próximo documento comece do zero:

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

Sem a chamada a libxml_clear_errors() ao final de cada iteração, os erros de a.xml ainda apareceriam ao relatar os erros de b.xml.

Problemas Comuns

• Limpar não desativa a coleta de erros. libxml_clear_errors() apenas esvazia o buffer; o libxml continua coletando novos erros enquanto libxml_use_internal_errors(true) estiver em vigor.
• É global. O buffer é compartilhado entre DOMDocument, SimpleXML e XMLReader. Limpá-lo afeta todos eles.
• A ordem importa. Sempre leia os erros com libxml_get_errors() antes de limpar — uma vez limpos, eles se perdem.

Funções Relacionadas

• libxml_use_internal_errors() — ativa ou desativa o buffer interno de erros.
• libxml_get_errors() — obtém todos os erros atualmente no buffer.
• libxml_get_last_error() — obtém apenas o erro mais recente.

Conclusão

A função libxml_clear_errors() oferece uma maneira simples de gerenciar o buffer interno de erros do libxml. Ao redefinir o buffer após operações como DOMDocument::load() ou DOMDocument::schemaValidate(), você evita que erros antigos vazem para resultados posteriores — o que é mais importante em loops e scripts de longa duração.

Prática