xml_get_current_line_number()

La función xml_get_current_line_number() es una función integrada de PHP que recupera el número de línea actual de un analizador XML. Pertenece a la extensión procedural XML Parser (Expat) y se utiliza al analizar XML con las funciones de estilo SAX xml_parse*. Conocer el número de línea actual resulta útil para depuración, reporte de errores y seguimiento del progreso del análisis.

Esta página cubre la sintaxis de la función, su valor de retorno y ejemplos prácticos, tanto con un análisis en un solo paso como dentro de un manejador de eventos SAX activo.

Cuándo utilizarla

Llama a xml_get_current_line_number() cuando necesites la posición del analizador en el documento fuente, típicamente en estos casos:

• Reporte de errores — cuando un manejador de eventos o xml_get_error_code() señala un problema, el número de línea indica al usuario dónde ocurrió en el archivo.
• Seguimiento del progreso — imprime qué línea se está procesando mientras se analiza un archivo XML grande.
• Diagnóstico — combínalo con xml_get_current_column_number() y xml_get_current_byte_index() para obtener una ubicación precisa línea:columna.

Esta función forma parte de la API Expat procedural. Si analizas XML con la clase orientada a objetos XMLReader, usa su método getLineNo().

Sintaxis

La sintaxis de la función xml_get_current_line_number() es la siguiente:

xml_get_current_line_number($parser): int|false

Parámetro

• $parser — el analizador XML creado por xml_parser_create() (o xml_parser_create_ns()). En PHP 8+ es un objeto XMLParser; en PHP 7 y versiones anteriores es un recurso.

Valor de retorno

Devuelve el número de línea actual (un int, comenzando en la línea 1) a medida que el analizador lee el documento. Devuelve false si $parser no es un analizador válido. Durante el análisis, el valor refleja la línea de los datos que el analizador ha alcanzado, por lo que es más significativo cuando se lee dentro de un manejador de eventos.

Ejemplos de uso

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

Ejemplo 1: Recuperar el número de línea actual de un analizador XML

Supongamos que tienes un archivo XML data.xml que deseas analizar con la extensión XML Parser de PHP. Puedes utilizar la función xml_get_current_line_number() para recuperar el número de línea alcanzado tras el análisis, de la siguiente manera:

$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 crea un analizador XML usando xml_parser_create() y establece una opción para desactivar el plegado de mayúsculas. Luego usa xml_parse_into_struct() para analizar el archivo XML data.xml y almacenar el resultado en un array $values. Recupera el número de línea actual con xml_get_current_line_number(), que devuelve el número de línea del último elemento analizado, y lo imprime en la consola. Finalmente, libera la memoria usada por el analizador XML con xml_parser_free().

Ejemplo 2: Seguimiento de números de línea durante el análisis SAX

Supongamos que deseas rastrear el número de línea de cada elemento a medida que se analiza mediante un manejador de eventos SAX. Puedes usar xml_set_element_handler() junto con xml_get_current_line_number() para monitorear la posición del analizador en tiempo real, de la siguiente manera:

$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 crea un analizador XML usando xml_parser_create() y registra un manejador de elementos con xml_set_element_handler(). Luego usa xml_parse() para analizar el archivo XML data.xml. Cada vez que se encuentra una etiqueta de apertura, el manejador recupera el número de línea actual con xml_get_current_line_number() y muestra el nombre del elemento junto con su posición en la línea. Finalmente, libera el analizador con xml_parser_free(). Como el número de línea se lee durante el callback, refleja la posición real de cada elemento — a diferencia del Ejemplo 1, donde el valor refleja solo el estado final después de que se analizó el documento completo.

Error común

xml_get_current_line_number() es significativa únicamente mientras el análisis está en progreso, lo que en la práctica significa dentro de un manejador de eventos. Si la llamas después de que xml_parse() ha terminado (como en el Ejemplo 1), obtendrás la línea del último byte consumido, no la línea de ningún elemento específico. Para posiciones por elemento, siempre léela dentro del manejador como se muestra en el Ejemplo 2.

Funciones relacionadas

• xml_get_current_column_number() — la columna dentro de la línea actual.
• xml_get_current_byte_index() — el desplazamiento en bytes dentro del documento.
• xml_get_error_code() y xml_error_string() — convierten un fallo de análisis en un mensaje legible.
• xml_set_element_handler() — registra los callbacks de etiquetas de apertura/cierre usados en el Ejemplo 2.

Conclusión

En este artículo, hemos analizado la función xml_get_current_line_number() de PHP y cómo recupera el número de línea actual de un analizador XML. Explicamos qué hace la función, su sintaxis y valor de retorno, y la mostramos tanto en un análisis en un solo paso como en un manejador SAX activo. Al leer el número de línea dentro de los manejadores de eventos, puedes localizar con precisión los elementos en el documento fuente para depuración, reporte de errores y seguimiento del progreso.

Práctica