xml_get_current_line_number()

A função xml_get_current_line_number() é uma função nativa do PHP que recupera o número da linha atual de um parser XML. Ela pertence à extensão procedural XML Parser (Expat) e é utilizada ao analisar XML com as funções de estilo SAX xml_parse*. Conhecer o número da linha atual é útil para depuração, relatório de erros e acompanhamento do progresso da análise.

Esta página aborda a sintaxe da função, seu valor de retorno e exemplos práticos — tanto com uma análise única quanto dentro de um handler de eventos SAX ativo.

Quando usar

Chame xml_get_current_line_number() sempre que precisar da posição do parser no documento fonte, normalmente:

• Relatório de erros — quando um handler de eventos ou xml_get_error_code() sinaliza um problema, o número da linha indica ao usuário onde no arquivo ele ocorreu.
• Rastreamento de progresso — exibe qual linha está sendo processada durante a análise de um arquivo XML grande.
• Diagnósticos — combine com xml_get_current_column_number() e xml_get_current_byte_index() para obter uma localização precisa no formato linha:coluna.

Esta função faz parte da API Expat procedural. Se você analisar XML com a classe orientada a objetos XMLReader, use seu método getLineNo().

Sintaxe

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

xml_get_current_line_number($parser): int|false

Parâmetro

• $parser — o parser XML criado por xml_parser_create() (ou xml_parser_create_ns()). No PHP 8+ este é um objeto XMLParser; no PHP 7 e anteriores é um resource.

Valor de retorno

Retorna o número da linha atual (um int, começando na linha 1) conforme o parser lê o documento. Retorna false se $parser não for um parser válido. Durante a análise, o valor reflete a linha dos dados que o parser alcançou — portanto, é mais significativo quando lido dentro de um handler de eventos.

Exemplos de uso

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

Exemplo 1: Recuperando o número da linha atual de um parser XML

Suponha que você tenha um arquivo XML data.xml que deseja analisar usando a extensão XML Parser do PHP. Você pode usar a função xml_get_current_line_number() para recuperar o número da linha alcançado após a análise, assim:

$xml_parser = xml_parser_create();
xml_parser_set_option($xml_parser, XML_OPTION_CASE_FOLDING, 0);
xml_parse_into_struct($xml_parser, file_get_contents("data.xml"), $values);
$current_line_number = xml_get_current_line_number($xml_parser);
echo "Current Line Number: $current_line_number";
xml_parser_free($xml_parser);

Este código cria um parser XML usando xml_parser_create() e define uma opção para desativar o case folding. Em seguida, usa xml_parse_into_struct() para analisar o arquivo XML data.xml e armazenar o resultado em um array $values. Ele recupera o número da linha atual usando xml_get_current_line_number(), que retorna o número da linha do último elemento analisado, e o imprime no console. Por fim, libera a memória usada pelo parser XML com xml_parser_free().

Exemplo 2: Rastreando números de linha durante a análise SAX

Suponha que você queira rastrear o número da linha de cada elemento conforme ele é analisado usando um handler de eventos SAX. Você pode usar xml_set_element_handler() junto com xml_get_current_line_number() para monitorar a posição do parser em tempo real, assim:

$xml_parser = xml_parser_create();
xml_set_element_handler($xml_parser, function($parser, $name, $attrs) {
    $line = xml_get_current_line_number($parser);
    echo "Element <$name> found at line $line\n";
}, function($parser, $name) {
    // end element handler
});
$xml_data = file_get_contents("data.xml");
xml_parse($xml_parser, $xml_data, true);
xml_parser_free($xml_parser);

Este código cria um parser XML usando xml_parser_create() e registra um handler de elementos com xml_set_element_handler(). Em seguida, usa xml_parse() para analisar o arquivo XML data.xml. Cada vez que uma tag de abertura é encontrada, o handler recupera o número da linha atual com xml_get_current_line_number() e exibe o nome do elemento junto com sua posição na linha. Por fim, libera o parser com xml_parser_free(). Como o número da linha é lido durante o callback, ele reflete a posição real de cada elemento — diferentemente do Exemplo 1, onde o valor reflete apenas o estado final após todo o documento ter sido analisado.

Problema comum

xml_get_current_line_number() é significativa apenas enquanto a análise está em andamento, o que na prática significa dentro de um handler de eventos. Se você a chamar após xml_parse() ter concluído (como no Exemplo 1), você obtém a linha do último byte consumido, não a linha de nenhum elemento específico. Para posições por elemento, sempre leia-a dentro do handler, conforme mostrado no Exemplo 2.

Funções relacionadas

• xml_get_current_column_number() — a coluna dentro da linha atual.
• xml_get_current_byte_index() — o deslocamento em bytes no documento.
• xml_get_error_code() e xml_error_string() — convertem uma falha de análise em uma mensagem legível.
• xml_set_element_handler() — registra os callbacks de tag de abertura/fechamento usados no Exemplo 2.

Conclusão

Neste artigo, discutimos a função xml_get_current_line_number() do PHP e como ela recupera o número da linha atual de um parser XML. Abordamos o que a função faz, sua sintaxe e valor de retorno, e a demonstramos tanto em uma análise única quanto em um handler SAX ativo. Ao ler o número da linha dentro dos seus handlers de eventos, você pode localizar com precisão os elementos no documento fonte para depuração, relatório de erros e rastreamento de progresso.

Prática