xml_get_current_column_number()

A função xml_get_current_column_number() é uma função nativa do PHP que obtém o número da coluna atual de um parser XML — o deslocamento horizontal de caracteres (base 1) dentro da linha atual que o parser atingiu. Ela pertence à extensão legada XML Parser (Expat), não ao SimpleXML ou DOM, e só é significativa enquanto uma análise está em andamento.

Esta página aborda o que a função retorna, sua sintaxe e exemplos executáveis que mostram o número da coluna reportado dentro dos manipuladores de eventos SAX. É mais útil para identificar a localização de um elemento ou erro na entrada — por exemplo, para escrever uma mensagem de log precisa ou um diagnóstico útil do tipo "erro de sintaxe próximo à coluna X".

Como o valor reflete a posição ao vivo do parser, você deve chamá-lo de dentro de um manipulador (ou logo após xml_parse() falhar). Ele combina naturalmente com xml_get_current_line_number() e xml_get_current_byte_index() para descrever completamente uma posição.

Sintaxe

xml_get_current_column_number(XMLParser $parser): int|false

$parser é o parser XML criado por xml_parser_create() (no PHP 8.0+ é um objeto XMLParser; em versões anteriores era um resource). A função retorna o número da coluna como um inteiro, ou false se $parser não for um parser válido.

Exemplos de Uso

Vamos ver alguns exemplos práticos do uso de xml_get_current_column_number() em PHP.

Exemplo 1: Obtendo o Número da Coluna Atual de um Parser XML

Suponha que você tenha uma string XML que deseja analisar usando a extensão legada XML Parser do PHP. Você pode chamar xml_get_current_column_number() dentro de um manipulador de eventos SAX — registrado com xml_set_element_handler() — para obter a coluna onde cada tag começa:

$xml_parser = xml_parser_create();
xml_set_element_handler($xml_parser, function($parser, $name) {
    echo "Start tag: $name at column " . xml_get_current_column_number($parser) . "\n";
}, function($parser, $name) {
    echo "End tag: $name\n";
});

$xml_data = "<root>\n  <item>Test</item>\n</root>";
xml_parse($xml_parser, $xml_data);
xml_parser_free($xml_parser);

Este código cria um parser, registra manipuladores de elementos de início/fim e executa xml_parse() sobre os dados. Dentro do manipulador de tag de início, ele lê o número da coluna ao vivo e o imprime, depois libera o parser com xml_parser_free(). Observe que a coluna aponta para o caractere após o abridor da tag, portanto avança conforme o parser consome cada tag. A saída é:

Start tag: ROOT at column 6
Start tag: ITEM at column 8
End tag: ITEM
End tag: ROOT

Exemplo 2: Rastreando Números de Coluna Durante a Análise

Suponha que você precise rastrear a posição da coluna do conteúdo de texto durante a análise de um arquivo XML. Como xml_parse_into_struct() não preenche números de coluna em seu array de saída, o rastreamento em tempo real requer manipuladores de eventos no estilo SAX em vez de iteração pós-análise. Você pode registrar um manipulador de dados de caractere com xml_set_character_data_handler() para capturar posições de coluna à medida que o parser encontra texto:

$xml_parser = xml_parser_create();
xml_set_character_data_handler($xml_parser, function($parser, $data) {
    $col = xml_get_current_column_number($parser);
    echo "Text content found at column: $col\n";
});

$xml_data = "<root>\n  <item>Sample Data</item>\n</root>";
xml_parse($xml_parser, $xml_data);
xml_parser_free($xml_parser);

O manipulador de dados de caractere pode disparar mais de uma vez por nó de texto (por exemplo, em torno de espaços em branco e quebras de linha), então você normalmente verá várias colunas reportadas. Essa abordagem rastreia posições em tempo real, diferentemente da iteração de array pós-análise, que não pode acessar o estado dinâmico do parser. A saída para esta entrada é:

Text content found at column: 3
Text content found at column: 20
Text content found at column: 1

Notas e Armadilhas

• Chame durante a análise. O valor só faz sentido enquanto xml_parse() está em execução (dentro de um manipulador) ou imediatamente após um erro de análise. Fora dessa janela, não tem significado útil.
• Colunas são baseadas em 1 e por linha. A contagem é reiniciada a cada nova linha. Combine com xml_get_current_line_number() para obter uma localização completa linha:coluna.
• Índice de byte vs. coluna. Se você precisa do deslocamento absoluto desde o início do documento em vez da posição por linha, use xml_get_current_byte_index().
• Extensão legada. O XML Parser baseado em Expat é procedural e orientado a eventos. Para o manuseio moderno de documentos, prefira SimpleXML ou DOM — mas para streaming de arquivos grandes ou localização precisa de erros, esta extensão ainda é a ferramenta certa.

Conclusão

Neste artigo, discutimos a função xml_get_current_column_number() do PHP e como ela pode ser usada para obter o número da coluna atual de um parser XML em PHP. Explicamos o que a função faz, sua sintaxe e fornecemos exemplos de como ela pode ser usada em cenários práticos. Seguindo esses exemplos, você pode facilmente rastrear a posição atual de um parser XML durante a análise e usá-la em suas aplicações PHP para registro, depuração ou rastreamento de progresso.

Prática