xml_get_current_column_number()

Функция xml_get_current_column_number() — это встроенная функция PHP, которая возвращает текущий номер столбца XML-парсера — горизонтальное смещение символа (начиная с 1) в текущей строке, до которого дошёл парсер. Она относится к устаревшему расширению XML Parser (Expat), а не к SimpleXML или DOM, и имеет смысл только во время выполнения разбора.

На этой странице описывается, что возвращает функция, её синтаксис, а также запускаемые примеры, демонстрирующие номер столбца, сообщаемый из обработчиков событий SAX. Функция наиболее полезна для точного определения местоположения элемента или ошибки во входных данных — например, для формирования точного сообщения в журнале или диагностики вида «синтаксическая ошибка около столбца X».

Поскольку значение отражает текущую позицию парсера, вызывать функцию необходимо изнутри обработчика (или сразу после того, как xml_parse() завершился с ошибкой). Она органично сочетается с xml_get_current_line_number() и xml_get_current_byte_index() для полного описания позиции.

Синтаксис

xml_get_current_column_number(XMLParser $parser): int|false

$parser — это XML-парсер, созданный функцией xml_parser_create() (начиная с PHP 8.0 — объект типа XMLParser; в более ранних версиях — ресурс). Функция возвращает номер столбца в виде целого числа или false, если $parser не является допустимым парсером.

Примеры использования

Рассмотрим несколько практических примеров использования xml_get_current_column_number() в PHP.

Пример 1: Получение текущего номера столбца XML-парсера

Предположим, у вас есть XML-строка, которую вы хотите разобрать с помощью устаревшего расширения XML Parser в PHP. Вы можете вызвать xml_get_current_column_number() внутри обработчика событий SAX — зарегистрированного с помощью xml_set_element_handler() — чтобы получить столбец, где начинается каждый тег:

$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);

Этот код создаёт парсер, регистрирует обработчики открывающих и закрывающих тегов и запускает xml_parse() для обработки данных. Внутри обработчика открывающего тега считывается текущий номер столбца и выводится на экран, затем парсер освобождается с помощью xml_parser_free(). Обратите внимание, что столбец указывает на символ после открывающего символа тега, поэтому его значение увеличивается по мере того, как парсер обрабатывает каждый тег. Вывод будет следующим:

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

Пример 2: Отслеживание номеров столбцов во время разбора

Предположим, вам необходимо отслеживать позицию столбца текстового содержимого при разборе XML-файла. Поскольку xml_parse_into_struct() не заполняет номера столбцов в своём выходном массиве, отслеживание в реальном времени требует обработчиков событий в стиле SAX, а не итерации после разбора. Вы можете зарегистрировать обработчик символьных данных с помощью xml_set_character_data_handler(), чтобы фиксировать позиции столбцов по мере того, как парсер встречает текст:

$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);

Обработчик символьных данных может вызываться несколько раз для одного текстового узла (например, для пробельных символов и переносов строк), поэтому обычно выводится несколько номеров столбцов. Этот подход отслеживает позиции в реальном времени, в отличие от итерации по массиву после разбора, которая не имеет доступа к динамическому состоянию парсера. Вывод для этих входных данных:

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

Примечания и особенности

• Вызывайте во время разбора. Значение имеет смысл только пока выполняется xml_parse() (внутри обработчика) или сразу после ошибки разбора. За пределами этого контекста оно не несёт полезной информации.
• Столбцы нумеруются с 1 и отсчитываются в пределах строки. Счётчик сбрасывается при каждом переносе строки. Используйте его совместно с xml_get_current_line_number(), чтобы получить полное местоположение в формате строка:столбец.
• Байтовый индекс и номер столбца. Если вам нужно абсолютное смещение от начала документа, а не позиция в пределах строки, используйте xml_get_current_byte_index().
• Устаревшее расширение. XML Parser на основе Expat является процедурным и событийно-ориентированным. Для большинства современных задач работы с документами предпочтительнее SimpleXML или DOM — однако для потоковой обработки больших файлов или точного определения местоположения ошибок это расширение по-прежнему является подходящим инструментом.

Заключение

В этой статье мы рассмотрели функцию PHP xml_get_current_column_number() и способы её использования для получения текущего номера столбца XML-парсера в PHP. Мы объяснили, что делает функция, описали её синтаксис и привели примеры практического применения. Следуя этим примерам, вы можете легко отслеживать текущую позицию XML-парсера во время разбора и использовать её в своих PHP-приложениях для ведения журнала, отладки или отслеживания прогресса.

Практика