xml_error_string()

A função xml_error_string() é uma função interna do PHP que recupera uma descrição textual de um erro do parser XML. Ela pertence à extensão legada XML Parser. Ao analisar arquivos XML com SimpleXML ou outras bibliotecas modernas, os erros são geralmente tratados com libxml_get_errors(), pois a extensão xml legada está depreciada no PHP moderno.

A função xml_error_string() é útil quando você precisa recuperar uma mensagem de erro legível para fluxos de trabalho legados de análise XML, embora aplicações modernas devam preferir libxml_get_errors() para SimpleXML.

Sintaxe

A sintaxe da função xml_error_string() é a seguinte:

sintaxe da função xml_error_string()

xml_error_string(int $error_code): string|false

Parâmetros

• $error_code — um código de erro inteiro, conforme retornado por xml_get_error_code(). A extensão XML Parser expõe esses códigos como constantes XML_ERROR_* (por exemplo, XML_ERROR_NONE é 0, significando "sem erro").

Valor de retorno

xml_error_string() retorna uma string legível descrevendo o código de erro fornecido (como "Attribute without value"). Se o código for desconhecido, retorna false. Observe que a função apenas converte um código em texto — ela não informa onde no documento o erro ocorreu; para isso, você também precisará de xml_get_current_line_number() e xml_get_current_column_number().

Exemplos de Uso

Vejamos alguns exemplos práticos de uso de xml_error_string() em PHP.

Exemplo 1: Recuperando uma String de Erro do Parser XML (XML Parser Legado)

A função xml_error_string() funciona com a extensão XML Parser legada. Você pode usá-la para analisar XML e recuperar a string de erro, assim:

analisar o arquivo XML e recuperar a string de erro usando xml_error_string() em PHP

$parser = xml_parser_create();
$xml_data = "<invalid xml>";
xml_parse($parser, $xml_data);

$error_code = xml_get_error_code($parser);
if ($error_code !== XML_ERROR_NONE) {
  $error_string = xml_error_string($error_code);
  echo "Error: $error_string";
}

xml_parser_free($parser);

Este código cria um parser XML com xml_parser_create(), tenta analisar a string malformada "<invalid xml>" (o xml é lido como um nome de atributo sem valor) e verifica a existência de erros. xml_get_error_code() retorna um código diferente de zero, xml_error_string() converte esse código em texto, e o script libera o parser com xml_parser_free().

Saída:

Error: Attribute without value

Exemplo 2: Identificando Onde o Erro Ocorreu

Uma string de erro isolada raramente ajuda o desenvolvedor a corrigir o documento. Combine xml_error_string() com as funções de número de linha e coluna para informar exatamente onde o parser parou:

exibir a mensagem de erro junto com sua localização

$parser = xml_parser_create();
$xml_data = "<book>\n  <title>Hi</titlex>\n</book>";

if (!xml_parse($parser, $xml_data, true)) {
  $code = xml_get_error_code($parser);
  printf(
    "Error %d: %s at line %d, column %d\n",
    $code,
    xml_error_string($code),
    xml_get_current_line_number($parser),
    xml_get_current_column_number($parser)
  );
}

xml_parser_free($parser);

Aqui, a tag de fechamento </titlex> não corresponde à abertura <title>, portanto a análise falha na linha 2. As funções de localização informam o ponto exato:

Saída:

Error 76: Mismatched tag at line 2, column 21

O código numérico exato e a redação dependem da versão do libxml, mas xml_error_string() sempre retorna a mensagem legível correspondente para qualquer código que xml_get_error_code() reporte.

Exemplo 2: Tratando Erros do SimpleXML (Abordagem Moderna Recomendada)

Se você estiver usando a biblioteca SimpleXML, xml_error_string() não é aplicável. Em vez disso, use libxml_use_internal_errors(true) e libxml_get_errors() para tratar falhas de análise:

Exibindo uma Mensagem de Erro do Parser XML

libxml_use_internal_errors(true);

if (isset($_FILES["xml_file"])) {
  $xml = simplexml_load_file($_FILES["xml_file"]["tmp_name"]);
  if ($xml === false) {
    $errors = libxml_get_errors();
    foreach ($errors as $error) {
      echo "Error: " . $error->message;
    }
  } else {
    // process the XML file
  }
}

Este código habilita o tratamento interno de erros para SimpleXML, verifica se um arquivo XML foi enviado usando o array $_FILES e tenta carregar o arquivo. Se ocorrer um erro durante a análise, recupera os detalhes do erro com libxml_get_errors() e exibe a mensagem de erro ao usuário. Se nenhum erro ocorrer, o código pode processar o arquivo XML conforme necessário.

Códigos de erro comuns do parser XML

A extensão XML Parser define constantes nomeadas para os casos de "sem erro" e de bem-formação. O único valor com o qual você sempre pode contar é XML_ERROR_NONE (0), que significa que a análise foi bem-sucedida. Alguns códigos baixos comuns e as strings que xml_error_string() retorna para eles são:

Atenção: o inteiro exato que uma análise real retorna, e sua redação, são produzidos pela biblioteca subjacente libxml e variam entre versões do PHP/libxml — portanto, sempre passe o valor ao vivo de xml_get_error_code() para xml_error_string(), em vez de assumir um número fixo. Apenas a verificação de "sucesso" XML_ERROR_NONE (0) é estável entre versões.

Comparar com XML_ERROR_NONE (em vez de um 0 codificado diretamente) mantém a intenção da sua verificação de sucesso clara.

Funções relacionadas

• xml_get_error_code() — retorna o código numérico que você passa para xml_error_string().
• xml_parse() — executa o parser e dispara o erro que você então descreve.
• xml_get_current_line_number() / xml_get_current_column_number() — localizam o erro na origem.
• libxml_get_errors() — o equivalente moderno usado com SimpleXML.

Conclusão

Neste artigo, discutimos a função xml_error_string() do PHP e como ela pode ser usada para recuperar uma descrição textual de um erro do parser XML em fluxos de trabalho legados de análise XML. Explicamos o que a função faz, sua sintaxe e fornecemos exemplos de como ela pode ser usada. Para aplicações PHP modernas que utilizam SimpleXML, recomendamos o uso de libxml_use_internal_errors(true) e libxml_get_errors() para tratar falhas de análise, garantindo que suas aplicações web sejam mais robustas e fáceis de usar.

Prática