libxml_get_last_error()

A função libxml_get_last_error() no PHP recupera o último erro gerado pela biblioteca libxml — o analisador que alimenta as extensões DOMDocument, SimpleXML e XMLReader do PHP. Quando você analisa ou valida XML malformado, o libxml registra o que deu errado; esta função permite que você leia o registro mais recente para exibir uma mensagem útil em vez de um aviso incompreensível.

Esta página aborda o que a função retorna, como capturar erros com libxml_use_internal_errors(), as propriedades do objeto de erro e quando usar libxml_get_last_error() em vez das funções relacionadas.

Sintaxe

libxml_get_last_error(): LibXMLError|false

A função não recebe nenhum argumento. Ela retorna:

• Um objeto LibXMLError descrevendo o erro mais recente, ou
• false se nenhum erro tiver sido registrado desde a última chamada a libxml_clear_errors().

Por que você precisa disso

Por padrão, o libxml emite erros como avisos do PHP, que poluem sua saída e são difíceis de tratar programaticamente. O padrão usual é:

1. Chamar libxml_use_internal_errors(true) para suprimir os avisos e armazenar os erros em um buffer interno.
2. Analisar ou validar seu XML.
3. Ler o buffer com libxml_get_last_error() (somente o mais recente) ou libxml_get_errors() (todos eles).
4. Limpar o buffer com libxml_clear_errors() para que a próxima operação comece limpa.

Use libxml_get_last_error() quando você se importar apenas com o que acabou de falhar — por exemplo, para relatar por que uma única chamada de análise não teve sucesso.

O objeto LibXMLError

O objeto retornado expõe estas propriedades públicas:

Exemplo: capturando um erro de análise

Este exemplo analisa uma string XML intencionalmente corrompida (uma tag de fechamento ausente) e depois imprime o erro capturado. É completamente autocontido — nenhum arquivo externo é necessário:

<?php
// Store libxml errors in an internal buffer instead of emitting warnings
libxml_use_internal_errors(true);

// This XML is malformed: <title> is never closed
$badXml = '<book><title>PHP</book>';

$doc = new DOMDocument();
$doc->loadXML($badXml);

$error = libxml_get_last_error();

if ($error !== false) {
    echo "Error level:  " . $error->level   . PHP_EOL;
    echo "Error code:   " . $error->code    . PHP_EOL;
    echo "Line:         " . $error->line     . PHP_EOL;
    echo "Message:      " . trim($error->message) . PHP_EOL;
} else {
    echo "The XML parsed without errors." . PHP_EOL;
}

// Always clear the buffer when you are done with it
libxml_clear_errors();
?>

Saída:

Error level:  3
Line:         1
Message:      Premature end of data in tag book line 1

O code, column e o texto da mensagem exatos dependem da sua versão do libxml, mas a estrutura é sempre a mesma. level é 3 (LIBXML_ERR_FATAL) porque a tag não fechada torna o documento impossível de analisar. (code foi omitido da saída acima apenas porque seu valor é específico da versão.)

Exemplo: validando contra um esquema

Um uso comum no mundo real é relatar por que um documento falhou na validação de esquema:

<?php
libxml_use_internal_errors(true);

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

if ($doc->schemaValidate('example.xsd')) {
    echo "The XML document is valid.";
} else {
    $error = libxml_get_last_error();
    if ($error !== false) {
        echo "Validation failed: " . trim($error->message);
    }
}

libxml_clear_errors();
?>

Aqui verificamos o valor de retorno de libxml_get_last_error() contra false antes de acessar $error->message — acessar uma propriedade em false geraria seu próprio aviso.

Armadilhas comuns

• Você deve habilitar o tratamento interno de erros primeiro. Sem libxml_use_internal_errors(true), o libxml imprime avisos e o buffer interno permanece vazio, portanto libxml_get_last_error() retorna false.
• Limpe o buffer entre as operações. Os erros se acumulam. Se você não chamar libxml_clear_errors(), uma chamada posterior a libxml_get_last_error() pode retornar um erro obsoleto de uma análise anterior.
• Último significa o último, não "desta chamada". A função retorna o que está no final do buffer, independentemente de qual análise o produziu.

Funções relacionadas

• libxml_get_errors() — retorna um array de todos os erros armazenados no buffer, não apenas o mais recente.
• libxml_clear_errors() — esvazia o buffer de erros.
• libxml_use_internal_errors() — alterna entre armazenar erros no buffer ou emiti-los como avisos.

Para um contexto mais amplo sobre como analisar XML no PHP, veja The XML DOM in PHP e SimpleXML.

Conclusão

libxml_get_last_error() oferece acesso programático ao erro mais recente de análise ou validação de XML, transformando falhas silenciosas e avisos ruidosos em mensagens acionáveis. Use-a junto com libxml_use_internal_errors() para capturar erros e libxml_clear_errors() para redefinir o buffer, e utilize libxml_get_errors() quando precisar da lista completa em vez de apenas a mais recente.

Prática