xml_get_error_code()

A função xml_get_error_code() é uma função interna do PHP que recupera o código de erro de um analisador XML. Quando você analisa XML com a extensão XML Parser (Expat) do PHP, as funções de análise retornam false no momento em que algo dá errado — mas apenas false não informa o que deu errado. xml_get_error_code() retorna um código numérico descrevendo o erro mais recente, que você pode então traduzir em uma mensagem legível por humanos com xml_error_string().

Esta página aborda a sintaxe da função, o que ela retorna, como converter o código em uma mensagem e o problema que pega a maioria das pessoas de surpresa: o código retornado é um código de erro Expat, não a constante XML_OPTION_* que você poderia esperar.

Sintaxe

xml_get_error_code(XMLParser $parser): int

$parser é o analisador criado por xml_parser_create() (ou xml_parser_create_ns()). No PHP 8.0+ é um objeto XMLParser; no PHP 7.x e anteriores era um resource. O código neste capítulo funciona em ambos.

Valor de retorno

A função retorna um código de erro do tipo integer:

• 0 (a constante XML_ERROR_NONE) significa nenhum erro — a análise foi bem-sucedida.
• Qualquer valor diferente de zero identifica o tipo de falha. Passe-o para xml_error_string() para obter uma descrição legível, e para xml_get_current_line_number() para encontrar onde ocorreu.

Sempre verifique o valor de retorno da função de análise primeiro (xml_parse() / xml_parse_into_struct()); chame xml_get_error_code() somente após ela retornar false.

Um exemplo completo e executável

O exemplo abaixo analisa uma string XML deliberadamente quebrada (a tag de fechamento não corresponde à de abertura), e então informa o código de erro, sua mensagem e o número da linha. Como o XML está incorporado como string, você pode copiá-lo e executá-lo como está — nenhum arquivo é necessário.

<?php
$broken = "<note><to>Ann</from></note>";   // </from> should be </to>

$parser = xml_parser_create();
if (!xml_parse_into_struct($parser, $broken, $values)) {
    $code = xml_get_error_code($parser);
    echo "Error code:  $code\n";
    echo "Message:     " . xml_error_string($code) . "\n";
    echo "On line:     " . xml_get_current_line_number($parser) . "\n";
}
xml_parser_free($parser);

Saída:

Error code:  76
Message:     Mismatched tag
On line:     1

xml_parse_into_struct() retorna false, então chamamos xml_get_error_code() e passamos o resultado diretamente para xml_error_string() para obter a mensagem "Mismatched tag".

O problema: o código é um código Expat

É tentador comparar o resultado com constantes como XML_ERROR_TAG_MISMATCH em um switch:

switch ($code) {
    case XML_ERROR_TAG_MISMATCH:  // value 7
        // ...
}

Mas esse bloco nunca corresponde. O analisador Expat retorna 76 para uma tag incompatível, enquanto XML_ERROR_TAG_MISMATCH é a constante 7 — são esquemas de numeração diferentes, então a comparação falha silenciosamente. A abordagem confiável é sempre converter o código em texto com xml_error_string() em vez de comparar números brutos:

<?php
$samples = [
    'good'      => "<note><to>Ann</to></note>",
    'mismatch'  => "<note><to>Ann</from></note>",
    'truncated' => "<note><to>Ann",
];

foreach ($samples as $label => $xml) {
    $parser = xml_parser_create();
    $ok = xml_parse_into_struct($parser, $xml, $values);
    $code = xml_get_error_code($parser);
    printf("%-9s -> code %d (%s)\n", $label, $code, xml_error_string($code) ?: 'OK');
    xml_parser_free($parser);
}

Saída:

good      -> code 0 (No error)
mismatch  -> code 76 (Mismatched tag)
truncated -> code 5 (Invalid document end)

Um código de 0 (XML_ERROR_NONE) confirma que o documento foi analisado corretamente, que é exatamente o que a amostra bem formada good produz.

Exibindo o erro para o usuário

Em uma aplicação real — por exemplo, um handler para um arquivo XML enviado — você normalmente registra o detalhe técnico e exibe a mensagem amigável:

$parser = xml_parser_create();
$xml    = file_get_contents($_FILES['xml_file']['tmp_name']);

if (!xml_parse_into_struct($parser, $xml, $values)) {
    $code = xml_get_error_code($parser);
    $line = xml_get_current_line_number($parser);

    // For the logs / developers:
    error_log("XML parse failed on line $line: " . xml_error_string($code));

    // For the user:
    $userMessage = "We couldn't read that file — please check it is valid XML.";
}
xml_parser_free($parser);

Quando usar (e quando não usar)

xml_get_error_code() pertence à extensão XML Parser baseada em Expat — a mesma família de xml_parser_create() e xml_parse_into_struct(). Use-a quando estiver fazendo análise baseada em eventos/stream com essa extensão e precisar reagir a uma falha.

Se você analisa XML com SimpleXML ou DOM, esta função não se aplica — elas usam a API de erros do libxml. Nesse caso, use libxml_get_last_error() (após chamar libxml_use_internal_errors(true)) para inspecionar o que deu errado. Consulte a visão geral do SimpleXML para esse fluxo de trabalho.

Conclusão

xml_get_error_code() recupera o código de erro numérico Expat da última falha em uma instância do XML Parser. O padrão confiável é: verificar o valor de retorno da função de análise e, se for false, chamar xml_get_error_code() e passar o resultado para xml_error_string() para obter uma mensagem legível — não compare o código bruto com constantes XML_ERROR_*, pois a numeração Expat não corresponde a elas. Use-a junto com xml_get_current_line_number() para apontar aos usuários (e aos seus logs) o local exato onde o documento falhou.

Prática