libxml_get_errors()

A função libxml_get_errors() no PHP recupera a lista de erros e avisos gerados pelas funções libxml — a biblioteca C que alimenta as extensões DOMDocument, SimpleXML e XMLReader do PHP. Ela é normalmente chamada após o parsing ou a validação de um documento XML para que você possa inspecionar exatamente o que deu errado, em vez de depender dos avisos do PHP.

Esta página cobre a assinatura da função, a estrutura dos objetos de erro que ela retorna, um exemplo funcional e autocontido, como interpretar os níveis de severidade dos erros e como ela se relaciona com as outras funções de erro do libxml.

Sintaxe

libxml_get_errors(): array

Não recebe nenhum argumento e retorna um array de objetos LibXMLError. Se não houver erros no buffer, retorna um array vazio ([]).

O que libxml_get_errors() retorna

Cada elemento do array retornado é um objeto LibXMLError com as seguintes propriedades públicas:

Como usar libxml_get_errors()

Há uma regra que você deve seguir: ative o tratamento interno de erros primeiro. Por padrão, o libxml escreve os erros de parsing diretamente na saída do PHP como avisos, e o buffer de erros permanece vazio. Chamar libxml_use_internal_errors(true) redireciona esses erros para um buffer interno que libxml_get_errors() consegue ler.

O fluxo típico é:

1. Chame libxml_use_internal_errors(true) antes do parsing.
2. Faça o parsing ou a validação do XML (com DOMDocument, SimpleXML, etc.).
3. Chame libxml_get_errors() para ler os erros coletados.
4. Chame libxml_clear_errors() para esvaziar o buffer antes da próxima operação.

Um exemplo funcional e autocontido

Este exemplo carrega um XML malformado a partir de uma string (sem necessidade de arquivos externos) e imprime cada erro com sua severidade, linha e coluna:

<?php
// 1. Capture errors in the internal buffer instead of emitting warnings
libxml_use_internal_errors(true);

// Intentionally broken XML: <author> is never closed
$xml = <<<XML
<book>
  <title>PHP Basics</title>
  <author>Jane Doe
</book>
XML;

// 2. Parse it
$doc = new DOMDocument();
$doc->loadXML($xml);

// 3. Read the errors
$errors = libxml_get_errors();

// Map numeric levels to readable labels
$levels = [
    LIBXML_ERR_WARNING => 'Warning',
    LIBXML_ERR_ERROR   => 'Error',
    LIBXML_ERR_FATAL   => 'Fatal',
];

foreach ($errors as $error) {
    printf(
        "[%s] line %d, col %d: %s",
        $levels[$error->level] ?? 'Unknown',
        $error->line,
        $error->column,
        $error->message            // already ends with a newline
    );
}

// 4. Clear the buffer so it doesn't leak into later parsing
libxml_clear_errors();
?>

Saída:

[Fatal] line 4, col 8: Opening and ending tag mismatch: author line 3 and book
[Fatal] line 4, col 8: Premature end of data in tag book line 1

Como a tag <author> foi deixada aberta, o libxml reporta dois erros fatais, cada um apontando para a linha e coluna exatas onde o problema foi detectado. Ler level, line e column — em vez de apenas message — é o que torna libxml_get_errors() tão útil para criar feedbacks de validação precisos.

Validando contra um esquema

O mesmo padrão funciona para validação de esquemas. Após schemaValidate() / schemaValidateSource() retornar false, os erros de validação estão aguardando no buffer:

<?php
libxml_use_internal_errors(true);

$doc = new DOMDocument();
$doc->load('example.xml');

// schemaValidateSource() validates against an in-memory XSD string
$xsd = file_get_contents('example.xsd');

if ($doc->schemaValidateSource($xsd)) {
    echo "The XML document is valid.\n";
} else {
    echo "The XML document is not valid:\n";
    foreach (libxml_get_errors() as $error) {
        echo trim($error->message) . "\n";
    }
}

libxml_clear_errors();
?>

Dica: Se você precisar apenas do problema mais recente, use libxml_get_last_error() — ele retorna um único objeto LibXMLError (ou false) em vez de todo o array.

Erros Comuns

• Resultado vazio? Você provavelmente esqueceu de chamar libxml_use_internal_errors(true). Sem isso, o buffer nunca é preenchido.
• Erros antigos. O buffer é compartilhado entre todas as operações do libxml na requisição. Sempre chame libxml_clear_errors() após terminar de processar um lote, ou erros anteriores reaparecerão em uma chamada posterior de libxml_get_errors().
• Avisos vs. fatais. Um array não vazio não significa necessariamente que o documento é inutilizável — filtre por $error->level >= LIBXML_ERR_ERROR se quiser ignorar os avisos.

Funções Relacionadas

• libxml_use_internal_errors() — ativa ou desativa o buffer de erros.
• libxml_get_last_error() — obtém apenas o erro mais recente.
• libxml_clear_errors() — esvazia o buffer de erros.
• Visão geral do PHP libxml — a extensão mais ampla a que essas funções pertencem.
• PHP XML DOM — parsing de documentos com DOMDocument.

Conclusão

A função libxml_get_errors() é uma ferramenta essencial para depurar operações XML no PHP. Ao ativar o tratamento interno de erros com libxml_use_internal_errors(true), fazer o parsing do documento e inspecionar as propriedades level, line, column e message de cada objeto LibXMLError, você consegue construir validações XML precisas e amigáveis ao usuário em vez de engolir avisos brutos do PHP. Lembre-se de limpar o buffer com libxml_clear_errors() entre as operações.

Prática