xml_get_current_column_number()

La función xml_get_current_column_number() es una función integrada de PHP que recupera el número de columna actual de un analizador XML — el desplazamiento horizontal de caracteres (basado en 1) dentro de la línea actual que el analizador ha alcanzado. Pertenece a la extensión heredada XML Parser (Expat), no a SimpleXML ni a DOM, y solo tiene sentido mientras el análisis está en progreso.

Esta página explica qué devuelve la función, su sintaxis y ejemplos ejecutables que muestran el número de columna reportado desde dentro de los manejadores de eventos SAX. Es más útil para precisar la ubicación de un elemento o error en la entrada — por ejemplo, para escribir un mensaje de registro preciso o un diagnóstico útil de "error de sintaxis cerca de la columna X".

Dado que el valor refleja la posición en vivo del analizador, debes llamarla desde dentro de un manejador (o justo después de que falle xml_parse()). Se combina de forma natural con xml_get_current_line_number() y xml_get_current_byte_index() para describir completamente una posición.

Sintaxis

xml_get_current_column_number(XMLParser $parser): int|false

$parser es el analizador XML creado por xml_parser_create() (en PHP 8.0+ es un objeto XMLParser; en versiones anteriores era un recurso). La función devuelve el número de columna como un entero, o false si $parser no es un analizador válido.

Ejemplos de uso

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

Ejemplo 1: Obtener el número de columna actual de un analizador XML

Supongamos que tienes una cadena XML que deseas analizar usando la extensión heredada XML Parser en PHP. Puedes llamar a xml_get_current_column_number() dentro de un manejador de eventos SAX — registrado con xml_set_element_handler() — para recuperar la columna donde comienza cada etiqueta:

$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 crea un analizador, registra manejadores de elementos de inicio y fin, y ejecuta xml_parse() sobre los datos. Dentro del manejador de etiquetas de inicio, lee el número de columna en vivo y lo imprime, luego libera el analizador con xml_parser_free(). Ten en cuenta que la columna apunta al carácter después del abridor de etiqueta, por lo que avanza a medida que el analizador consume cada etiqueta. La salida es:

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

Ejemplo 2: Rastrear números de columna durante el análisis

Supongamos que necesitas rastrear la posición de columna del contenido de texto mientras analizas un archivo XML. Dado que xml_parse_into_struct() no incluye números de columna en su array de salida, el rastreo en tiempo real requiere manejadores de eventos de estilo SAX en lugar de iteración posterior al análisis. Puedes registrar un manejador de datos de caracteres con xml_set_character_data_handler() para capturar posiciones de columna a medida que el analizador encuentra 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);

El manejador de datos de caracteres puede activarse más de una vez por nodo de texto (por ejemplo, alrededor de espacios en blanco y saltos de línea), por lo que normalmente verás varias columnas reportadas. Este enfoque rastrea posiciones en tiempo real, a diferencia de la iteración por array posterior al análisis, que no puede acceder al estado dinámico del analizador. La salida para esta entrada es:

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

Notas y advertencias

• Llámala durante el análisis. El valor solo tiene sentido mientras xml_parse() está en ejecución (dentro de un manejador) o inmediatamente después de un error de análisis. Fuera de ese contexto no tiene un significado útil.
• Las columnas están basadas en 1 y son por línea. El conteo se reinicia en cada nueva línea. Combínala con xml_get_current_line_number() para obtener una ubicación completa línea:columna.
• Índice de bytes vs. columna. Si necesitas el desplazamiento absoluto desde el inicio del documento en lugar de la posición por línea, usa xml_get_current_byte_index().
• Extensión heredada. El XML Parser basado en Expat es procedural y orientado a eventos. Para el manejo moderno de documentos, prefiere SimpleXML o DOM — pero para transmitir archivos grandes o ubicaciones de error precisas, esta extensión sigue siendo la herramienta adecuada.

Conclusión

En este artículo, hemos analizado la función xml_get_current_column_number() de PHP y cómo se puede usar para recuperar el número de columna actual de un analizador XML en PHP. Hemos explicado qué hace la función, su sintaxis y hemos proporcionado ejemplos de cómo se puede usar en escenarios prácticos. Siguiendo estos ejemplos, puedes rastrear fácilmente la posición actual de un analizador XML durante el análisis y usarla en tus aplicaciones PHP para registro, depuración o seguimiento del progreso.

Práctica