xml_parser_set_option()

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

Синтаксис

xml_parser_set_option(XMLParser $parser, int $option, string|int $value): bool

• $parser — парсер, возвращённый функцией xml_parser_create(). Начиная с PHP 8.0 это объект XMLParser; в PHP 7 и более ранних версиях это был ресурс.
• $option — одна из констант параметров, перечисленных ниже.
• $value — значение, устанавливаемое для данного параметра.

Функция возвращает true при успехе или false, если парсер или параметр недействительны.

Доступные параметры

Прочитать текущее значение можно с помощью xml_parser_get_option(). Установка параметра после начала разбора не имеет эффекта, поэтому настраивайте парсер заранее.

Почему важна свёртка регистра

Это параметр, к которому вы будете обращаться чаще всего. По умолчанию парсер переводит в верхний регистр каждое имя тега, поэтому элемент <note> попадает в ваш обработчик как NOTE. Это удивляет разработчиков, сравнивающих имена со строками в нижнем регистре. Отключение свёртки регистра сохраняет имена точно в том виде, в каком они написаны:

$parser = xml_parser_create();

// Default behaviour: case folding ON → names arrive upper-cased
xml_set_element_handler($parser,
    fn($p, $name, $attrs) => print("Start: $name\n"),
    fn($p, $name) => null
);
xml_parse($parser, "<note><to>Tove</to></note>", true);
xml_parser_free($parser);

Вывод:

Start: NOTE
Start: TO

Установите XML_OPTION_CASE_FOLDING в false, и тот же входной текст сохранит исходный регистр (note, to).

Полный пример

Расширение XML Parser является событийно-ориентированным: ничего не происходит, пока вы не зарегистрируете обработчики и не подадите данные. В этом примере создаётся парсер, устанавливаются два параметра, регистрируются обработчики начала и конца элементов, после чего выполняется разбор встроенной строки XML — внешний файл не требуется, поэтому вы можете запустить его прямо так:

$parser = xml_parser_create();

// Keep the original tag case instead of upper-casing
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, false);
// Drop elements that contain only whitespace
xml_parser_set_option($parser, XML_OPTION_SKIP_WHITE, true);

xml_set_element_handler(
    $parser,
    function ($parser, $name, $attrs) {
        echo "Start: $name\n";
    },
    function ($parser, $name) {
        echo "End: $name\n";
    }
);

$xml = "<note>\n  <to>Tove</to>\n  <from>Jani</from>\n</note>";
xml_parse($parser, $xml, true);

xml_parser_free($parser);

Вывод:

Start: note
Start: to
End: to
Start: from
End: from
End: note

Поскольку свёртка регистра отключена, имена тегов сохраняют написание в нижнем регистре. Вызов xml_set_element_handler() позволяет xml_parse() генерировать эти события; без зарегистрированных обработчиков парсер прочитал бы документ, но не произвёл никакого вывода. Всегда вызывайте xml_parser_free() по завершении работы, чтобы освободить ресурсы парсера.

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

Используйте xml_parser_set_option() только тогда, когда вы уже работаете с низкоуровневым парсером Expat — как правило, для потоковой обработки очень больших XML-документов, когда загрузка всего дерева в память нежелательна. Для большинства повседневных задач (чтение конфигурации, обработка ответа API) предпочтительнее использовать SimpleXML, который значительно проще и не требует подобной настройки.

Заключение

xml_parser_set_option() настраивает устаревший XML-парсер в стиле SAX — в первую очередь поведение свёртки регистра, обработки пробельных символов и кодировки. Устанавливайте все параметры до вызова xml_parse(), регистрируйте обработчики элементов для генерации событий и освобождайте парсер после завершения. Когда требуется тонкая, экономичная по памяти потоковая обработка, эта функция обеспечивает необходимый контроль; в противном случае SimpleXML или DOM являются более простым выбором.

Практика