libxml_use_internal_errors()

A função libxml_use_internal_errors() permite informar às extensões PHP baseadas em libxml (DOM, SimpleXML, XMLReader, XMLWriter) para parar de imprimir avisos na tela e, em vez disso, coletá-los em um buffer interno que você pode inspecionar a partir do seu próprio código.

Esta página explica o que a função faz, sua assinatura e valor de retorno, e como combiná-la com o restante da API de erros do libxml para analisar XML mal formatado de forma elegante.

Por que usar o tratamento interno de erros?

Por padrão, quando o libxml encontra XML mal formado, ele emite warnings do PHP. Em uma aplicação web, esses avisos ou poluem a saída ou são silenciosamente suprimidos dependendo das configurações de display_errors/error_reporting — e você não tem uma forma estruturada de reagir a eles.

Chamar libxml_use_internal_errors(true) muda isso:

• O parsing não emite mais warnings do PHP. Seu script continua executando.
• Cada problema é inserido em um buffer interno como um objeto LibXMLError.
• Você decide o que fazer — registrar no log, exibir uma mensagem amigável, abortar ou ignorar problemas não fatais.

Este é o padrão habitual para analisar XML que você não controla (uploads de usuários, feeds de terceiros, HTML coletado via scraping).

Sintaxe

libxml_use_internal_errors(?bool $use_errors = null): bool

• $use_errors — passe true para ativar o tratamento interno de erros, false para desativá-lo. Passe null (ou omita o argumento) para consultar o estado atual sem alterá-lo.
• Valor de retorno — a função retorna a configuração anterior (um bool). Isso permite restaurar o estado antigo quando terminar, para não afetar código não relacionado.

Como usar libxml_use_internal_errors()

Ative os erros internos, analise o documento, depois leia o buffer com libxml_get_errors() e limpe-o com libxml_clear_errors().

O exemplo abaixo analisa XML mal formado inline (sem necessidade de arquivo externo, para que você possa executá-lo como está):

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

Saída:

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

Observe que nenhum warning do PHP foi impresso — o documento inválido produziu dois objetos de erro estruturados.

Lendo um objeto LibXMLError

Cada item retornado por libxml_get_errors() (ou libxml_get_last_error()) é um objeto LibXMLError com campos úteis:

Você pode usar level para ignorar avisos inofensivos enquanto ainda falha em erros fatais:

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

Saída:

Fatal parse error (code 77)

Restaurar o estado anterior

Como a função retorna a configuração anterior, uma biblioteca que ativa os erros internos deve restaurá-los depois para não alterar o comportamento do restante da aplicação:

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

Armadilhas comuns

• O buffer é global e persistente. Os erros se acumulam até que você chame libxml_clear_errors() (ou a requisição termine). Sempre limpe-o entre os parsings, ou você relerá erros antigos.
• Também afeta o carregamento de HTML. DOMDocument::loadHTML() reporta markup inválido pelo mesmo mecanismo — útil para fazer scraping de HTML imperfeito sem warnings.
• Desativar reativa os warnings do PHP. Chamar libxml_use_internal_errors(false) retorna o libxml ao seu padrão de emitir warnings/notices.

Conclusão

libxml_use_internal_errors() é a porta de entrada para o tratamento robusto de XML no PHP: ative-a para silenciar os warnings padrão do libxml, depois use libxml_get_errors(), libxml_get_last_error() e libxml_clear_errors() para inspecionar e gerenciar problemas por conta própria. Lembre-se do seu valor de retorno para restaurar o estado anterior e sempre limpe o buffer entre os parsings.

Prática