xml_get_current_byte_index()

La función xml_get_current_byte_index() es una función integrada de PHP que devuelve cuántos bytes del documento XML ya ha consumido el analizador. Forma parte de la extensión heredada XML Parser, que analiza documentos de forma continua al estilo SAX: en lugar de cargar todo el documento en un árbol, dispara callbacks mientras recorre el marcado. Esta función le indica dónde se encuentra el analizador cuando se ejecuta uno de esos callbacks.

Normalmente se llama desde dentro de un manejador registrado con xml_set_element_handler() o xml_set_character_data_handler(). Es más útil para informar sobre el progreso del análisis en un archivo grande, o para localizar dónde en el origen apareció un elemento o fragmento de contenido determinado; por ejemplo, para construir un mensaje de error que señale un desplazamiento de bytes.

Esta página cubre la sintaxis de la función, el valor de retorno, dos ejemplos prácticos y los aspectos a tener en cuenta.

Sintaxis

xml_get_current_byte_index(XMLParser $parser): int

Parámetros

• $parser — el identificador del analizador devuelto por xml_parser_create() o xml_parser_create_ns(). En PHP 8.0+ es un objeto XMLParser; en PHP 7.x es un resource.

Valor de retorno

Devuelve el desplazamiento en bytes (un entero con base cero) de la posición actual del analizador en el documento. Dado que cuenta bytes, no caracteres, un archivo UTF-8 multibyte reportará un índice mayor que su número de caracteres. Si necesita una línea o columna en su lugar, use las funciones complementarias xml_get_current_line_number() y xml_get_current_column_number().

El valor solo es significativo mientras el análisis está en progreso (es decir, dentro de un manejador). Llamarla antes de que xml_parse() haya comenzado devuelve 0.

Ejemplos de uso

Veamos algunos ejemplos prácticos del uso de xml_get_current_byte_index() en PHP.

Ejemplo 1: Obtener el índice de bytes actual de un analizador XML

Suponga que tiene un archivo XML "data.xml" que desea analizar con la extensión XML Parser de PHP. Puede usar la función xml_get_current_byte_index() dentro de un manejador de elementos SAX para obtener el índice de bytes actual cuando comienza un elemento, de la siguiente manera:

Obtener el índice de bytes actual de un analizador XML en 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 crea un analizador XML con xml_parser_create() y establece una opción para desactivar el plegado de mayúsculas. Define un callback start_handler que llama a xml_get_current_byte_index() para obtener la posición del analizador cada vez que comienza un elemento. El manejador se registra con xml_set_element_handler(), y xml_parse() procesa el archivo. Por último, libera la memoria utilizada por el analizador XML con xml_parser_free().

Ejemplo 2: Seguimiento del progreso del análisis

Suponga que tiene un archivo XML grande y desea mostrar un indicador de progreso mientras lo analiza. Puede usar la extensión XML Parser con un manejador de datos de caracteres para rastrear el índice de bytes mientras el analizador lee el archivo, de la siguiente manera:

Seguimiento del progreso del análisis en 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 crea un analizador XML y calcula el tamaño total del archivo. Define un callback progress_handler que compara el índice de bytes actual con la última posición reportada. Si se han leído más de 1 KB, calcula e imprime el porcentaje de análisis. El manejador se registra con xml_set_character_data_handler(), y xml_parse() procesa el archivo. Por último, libera la memoria utilizada por el analizador XML con xml_parser_free().

Notas y aspectos a tener en cuenta

• Bytes, no caracteres. En un documento UTF-8 con caracteres multibyte, el desplazamiento devuelto puede ser mayor que la posición del carácter. No lo trate como un conteo de caracteres.
• Llámela dentro de un manejador. El índice de bytes solo refleja una posición real mientras se ejecuta un callback. Fuera del análisis devuelve 0.
• El desplazamiento puede señalar ligeramente más allá del marcado. Dependiendo del almacenamiento en búfer de libexpat, el índice reportado puede estar al final del token que activó el callback en lugar de en su inicio exacto. Úselo para progreso aproximado y localización, no para fragmentación exacta de bytes.
• Esta es la API SAX heredada. Para la mayoría del código nuevo, las extensiones basadas en árbol SimpleXML o DOM son más sencillas. Recurra a la extensión XML Parser cuando necesite específicamente transmisión para archivos muy grandes. Consulte la descripción general de los analizadores XML de PHP para elegir.

Conclusión

En este artículo hemos analizado la función xml_get_current_byte_index() de PHP y cómo puede usarse para obtener el índice de bytes actual de un analizador XML durante el análisis al estilo SAX. Hemos explicado qué hace la función, su sintaxis y proporcionado ejemplos de cómo puede usarse en escenarios prácticos. Siguiendo estos ejemplos, puede rastrear fácilmente la posición del analizador y utilizarla en sus aplicaciones PHP para monitorear el progreso o localizar elementos específicos.

Práctica