xml_parser_get_option()

Функция xml_parser_get_option() читает текущее значение параметра конфигурации XML-парсера, созданного с помощью устаревшего расширения xml на основе Expat. Каждый парсер хранит небольшой набор параметров (свёртка регистра, целевая кодировка и пропуск пробелов), которые определяют, как он преобразует разметку в события. Устанавливаются они с помощью xml_parser_set_option(), а читаются обратно с помощью xml_parser_get_option().

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

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

Синтаксис

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

$parser — дескриптор парсера, возвращённый xml_parser_create() (начиная с PHP 8.0 это объект XMLParser, а не resource). $option — одна из констант XML_OPTION_*, перечисленных ниже. Тип возвращаемого значения зависит от параметра: boolean для флагов включения/выключения, integer для XML_OPTION_SKIP_TAGSTART и string для XML_OPTION_TARGET_ENCODING.

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

Запрос неизвестного параметра возвращает false.

Примеры

Чтение одного параметра

Этот код создаёт парсер, отключает свёртку регистра, а затем считывает параметр обратно. Поскольку возвращается false, сообщение выводит "disabled":

<?php
$parser = xml_parser_create();
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, false);

$caseFolding = xml_parser_get_option($parser, XML_OPTION_CASE_FOLDING);
echo "Case folding is " . ($caseFolding ? "enabled" : "disabled") . ".\n";

Вывод:

Case folding is disabled.

Проверка значений по умолчанию и подтверждение изменений

Новый парсер уже имеет разумные значения по умолчанию. Чтение их до и после вызова set — хороший способ убедиться, что конфигурация применилась:

<?php
$parser = xml_parser_create();

// Defaults on a brand-new parser.
echo "Default case folding: ";
var_dump(xml_parser_get_option($parser, XML_OPTION_CASE_FOLDING));   // bool(true)
echo "Default encoding: ";
var_dump(xml_parser_get_option($parser, XML_OPTION_TARGET_ENCODING)); // string(5) "UTF-8"

// Change two options, then confirm them.
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, false);
xml_parser_set_option($parser, XML_OPTION_SKIP_WHITE, true);

printf("Case folding now: %s\n", xml_parser_get_option($parser, XML_OPTION_CASE_FOLDING) ? "on" : "off");
printf("Skip whitespace:  %s\n", xml_parser_get_option($parser, XML_OPTION_SKIP_WHITE) ? "on" : "off");

Вывод:

Default case folding: bool(true)
Default encoding: string(5) "UTF-8"
Case folding now: off
Skip whitespace:  on

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

Примечания и нюансы

• Только чтение. Эта функция никогда не изменяет парсер. Для изменения параметра используйте xml_parser_set_option().
• Возвращает разные типы. Обрабатывайте результат в зависимости от параметра: bool-флаг, int для SKIP_TAGSTART или string для кодировки. Не ожидайте boolean для каждого параметра.
• Expat — низкоуровневый и устаревший API. Расширение xml (Expat) появилось раньше современных API. Если только вам специально не нужен событийный ("SAX") разбор очень больших документов, SimpleXML или DOM обычно проще и безопаснее. Обратите внимание, что XML_OPTION_CASE_FOLDING по умолчанию равен true — это классический сюрприз: имена элементов приходят в верхнем регистре, если не отключить эту опцию.
• Освобождайте парсер по завершении. Хотя PHP освобождает объект XMLParser самостоятельно, вы можете вызвать xml_parser_free() для явного освобождения.

Заключение

xml_parser_get_option() — это геттер-половина пары параметров парсера Expat: она возвращает текущее значение XML_OPTION_CASE_FOLDING, XML_OPTION_TARGET_ENCODING, XML_OPTION_SKIP_WHITE или XML_OPTION_SKIP_TAGSTART, не изменяя ничего. Используйте её для проверки конфигурации парсера перед вызовом xml_parse(). Для нового кода, не требующего низкоуровневого SAX-разбора, предпочтительнее использовать SimpleXML или расширение DOM.

Практика