xml_get_current_line_number()

Функция xml_get_current_line_number() — встроенная функция PHP, которая возвращает текущий номер строки парсера XML. Она входит в процедурное расширение XML Parser (Expat) и используется при разборе XML с помощью SAX-функций xml_parse*. Знание текущего номера строки полезно для отладки, сообщений об ошибках и отслеживания хода разбора.

На этой странице рассматривается синтаксис функции, её возвращаемое значение и практические примеры — как при однократном разборе, так и внутри живого SAX-обработчика событий.

Когда использовать

Вызывайте xml_get_current_line_number() каждый раз, когда вам нужна позиция парсера в исходном документе, как правило:

• Сообщения об ошибках — когда обработчик события или xml_get_error_code() сигнализирует о проблеме, номер строки сообщает пользователю где в файле она произошла.
• Отслеживание хода разбора — вывод информации о том, какая строка обрабатывается при разборе большого XML-файла.
• Диагностика — используйте в паре с xml_get_current_column_number() и xml_get_current_byte_index() для точного указания позиции в формате строка:столбец.

Эта функция является частью процедурного API Expat. Если вы разбираете XML с помощью объектно-ориентированного класса XMLReader, используйте его метод getLineNo().

Синтаксис

Синтаксис функции xml_get_current_line_number() выглядит следующим образом:

xml_get_current_line_number($parser): int|false

Параметр

• $parser — XML-парсер, созданный функцией xml_parser_create() (или xml_parser_create_ns()). В PHP 8+ это объект XMLParser; в PHP 7 и более ранних версиях — ресурс.

Возвращаемое значение

Возвращает текущий номер строки (int, начиная со строки 1) по мере того, как парсер читает документ. Возвращает false, если $parser не является допустимым парсером. Во время разбора значение отражает строку данных, которую парсер обрабатывает в данный момент — поэтому оно наиболее информативно при чтении внутри обработчика события.

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

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

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

Предположим, у вас есть XML-файл data.xml, который вы хотите разобрать с помощью расширения XML Parser в PHP. Для получения номера строки, достигнутой после разбора, можно использовать функцию xml_get_current_line_number(), как показано ниже:

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

Этот код создаёт XML-парсер с помощью xml_parser_create() и устанавливает параметр для отключения преобразования регистра. Затем он использует xml_parse_into_struct() для разбора XML-файла data.xml и сохранения результата в массиве $values. После этого функция xml_get_current_line_number() возвращает номер строки последнего разобранного элемента, который выводится в консоль. В конце память, занятая XML-парсером, освобождается с помощью xml_parser_free().

Пример 2: Отслеживание номеров строк при SAX-разборе

Предположим, вы хотите отслеживать номер строки каждого элемента по мере его разбора с помощью SAX-обработчика событий. Для мониторинга позиции парсера в реальном времени можно использовать xml_set_element_handler() совместно с xml_get_current_line_number(), как показано ниже:

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

Этот код создаёт XML-парсер с помощью xml_parser_create() и регистрирует обработчик элементов с помощью xml_set_element_handler(). Затем он использует xml_parse() для разбора XML-файла data.xml. Каждый раз, когда встречается открывающий тег, обработчик получает текущий номер строки с помощью xml_get_current_line_number() и выводит имя элемента вместе с его позицией в строке. В конце парсер освобождается с помощью xml_parser_free(). Поскольку номер строки считывается во время обратного вызова, он отражает реальную позицию каждого элемента — в отличие от примера 1, где значение отражает лишь конечное состояние после разбора всего документа.

Распространённая ловушка

xml_get_current_line_number() имеет смысл только в процессе разбора, то есть на практике — внутри обработчика события. Если вызвать её после завершения работы xml_parse() (как в примере 1), будет возвращена строка последнего обработанного байта, а не строка какого-либо конкретного элемента. Для получения позиций отдельных элементов всегда читайте её внутри обработчика, как показано в примере 2.

Связанные функции

• xml_get_current_column_number() — столбец в текущей строке.
• xml_get_current_byte_index() — смещение в байтах в документе.
• xml_get_error_code() и xml_error_string() — преобразование ошибки разбора в читаемое сообщение.
• xml_set_element_handler() — регистрация обратных вызовов для открывающих/закрывающих тегов, используемых в примере 2.

Заключение

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

Практика