xml_get_current_byte_index()

A função xml_get_current_byte_index() é uma função nativa do PHP que retorna quantos bytes do documento XML o parser já consumiu. Ela faz parte da extensão legada XML Parser, que analisa documentos de forma contínua, no estilo SAX: em vez de carregar o documento inteiro em uma árvore, dispara callbacks à medida que percorre o markup. Esta função informa onde o parser está quando um desses callbacks é executado.

Normalmente você a chama de dentro de um handler registrado com xml_set_element_handler() ou xml_set_character_data_handler(). É mais útil para reportar o progresso da análise em um arquivo grande, ou para localizar onde no código-fonte um determinado elemento ou trecho de conteúdo apareceu — por exemplo, para criar uma mensagem de erro que aponta para um deslocamento de bytes.

Esta página cobre a sintaxe da função, o valor de retorno, dois exemplos práticos e as armadilhas a observar.

Sintaxe

xml_get_current_byte_index(XMLParser $parser): int

Parâmetros

• $parser — o handle do parser retornado por xml_parser_create() ou xml_parser_create_ns(). No PHP 8.0+ é um objeto XMLParser; no PHP 7.x é um resource.

Valor de retorno

Retorna o deslocamento de bytes (um inteiro baseado em zero) da posição atual do parser no documento. Como conta bytes, não caracteres, um arquivo UTF-8 com caracteres multibyte reportará um índice maior do que a contagem de caracteres. Se precisar de uma linha ou coluna, use as funções complementares xml_get_current_line_number() e xml_get_current_column_number().

O valor só é significativo enquanto a análise está em andamento (ou seja, dentro de um handler). Chamá-la antes de xml_parse() ter iniciado retorna 0.

Exemplos de Uso

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

Exemplo 1: Recuperando o Índice de Byte Atual de um Parser XML

Suponha que você tenha um arquivo XML "data.xml" que deseja analisar usando a extensão XML Parser em PHP. Você pode usar a função xml_get_current_byte_index() dentro de um handler de elementos SAX para recuperar o índice de byte atual quando um elemento começa, assim:

Recuperando o Índice de Byte Atual de um Parser XML em PHP

$parser = xml_parser_create();
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, 0);

function start_handler($parser, $name, $attrs) {
    $byte_index = xml_get_current_byte_index($parser);
    echo "Element <$name> starts at byte index: $byte_index\n";
}

xml_set_element_handler($parser, "start_handler", null);

$xml_data = file_get_contents("data.xml");
xml_parse($parser, $xml_data, true);
xml_parser_free($parser);

Este código cria um parser XML usando xml_parser_create() e define uma opção para desativar o dobramento de maiúsculas. Ele define um callback start_handler que chama xml_get_current_byte_index() para obter a posição do parser sempre que um elemento começa. O handler é registrado com xml_set_element_handler(), e xml_parse() processa o arquivo. Por fim, libera a memória usada pelo parser XML com xml_parser_free().

Exemplo 2: Acompanhando o Progresso da Análise

Suponha que você tenha um arquivo XML grande e queira exibir um indicador de progresso durante a análise. Você pode usar a extensão XML Parser com um handler de dados de caracteres para rastrear o índice de bytes à medida que o parser lê o arquivo, assim:

Acompanhando o Progresso da Análise em PHP

$parser = xml_parser_create();
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, 0);

$total_bytes = filesize("data.xml");
$last_reported = 0;

function progress_handler($parser, $data) {
    global $last_reported, $total_bytes;
    $current = xml_get_current_byte_index($parser);
    if ($current - $last_reported > 1024) { // Report every 1KB
        $progress = round(($current / $total_bytes) * 100);
        echo "Parsing progress: $progress%\n";
        $last_reported = $current;
    }
}

xml_set_character_data_handler($parser, "progress_handler");
xml_parse($parser, file_get_contents("data.xml"), true);
xml_parser_free($parser);

Este código cria um parser XML e calcula o tamanho total do arquivo. Ele define um callback progress_handler que verifica o índice de bytes atual em relação à última posição reportada. Se mais de 1KB foi lido, calcula e imprime a porcentagem de análise. O handler é registrado com xml_set_character_data_handler(), e xml_parse() processa o arquivo. Por fim, libera a memória usada pelo parser XML com xml_parser_free().

Observações e Armadilhas

• Bytes, não caracteres. Em um documento UTF-8 com caracteres multibyte, o deslocamento retornado pode ser maior do que a posição do caractere. Não o trate como uma contagem de caracteres.
• Chame-a dentro de um handler. O índice de bytes só reflete uma posição real enquanto um callback está sendo executado. Fora da análise, retorna 0.
• O deslocamento pode apontar ligeiramente além do markup. Dependendo do buffer do libexpat, o índice reportado pode estar no final do token que acionou o callback, e não no início exato. Use-o para progresso aproximado e localização, não para fatiamento exato de bytes.
• Esta é a API SAX legada. Para a maioria dos novos códigos, as extensões baseadas em árvore SimpleXML ou DOM são mais simples. Recorra à extensão XML Parser especificamente quando precisar de streaming para arquivos muito grandes. Consulte a visão geral dos parsers XML do PHP para escolher.

Conclusão

Neste artigo, discutimos a função xml_get_current_byte_index() do PHP e como ela pode ser usada para recuperar o índice de byte atual de um parser XML durante a análise no estilo SAX. 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 do parser e usá-la em suas aplicações PHP para monitorar o progresso ou localizar elementos específicos.

Prática