xml_set_processing_instruction_handler()

Функция xml_set_processing_instruction_handler() устанавливает пользовательскую функцию в качестве обработчика инструкций обработки в XML-парсере. Она относится к устаревшему расширению xml (Expat / SAX) и используется для событийного разбора, а не с библиотекой SimpleXML. Каждый раз, когда парсер встречает инструкцию обработки в документе, он вызывает ваш обработчик, чтобы вы могли на неё отреагировать — например, извлечь встроенные директивы или запустить какое-либо действие в процессе разбора.

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

⚠️ Уведомление об устаревании: Расширение xml было признано устаревшим в PHP 8.0 и полностью удалено в PHP 8.2. Эта функция доступна только в PHP 7.4 и более ранних версиях. Для современных проектов используйте XMLReader или DOMDocument.

Что такое инструкция обработки?

Инструкция обработки (PI) — это специальный узел XML, который передаёт приложению-обработчику документа специфичные для него директивы. Это не содержимое элемента — она располагается между разметкой. PI состоит из двух частей: цель (имя сразу после <?) и данные (всё до закрывающего ?>):

<?target data ?>

Например, <?php-cache ttl="60" ?> имеет цель php-cache и данные ttl="60". XML-объявление <?xml version="1.0"?> выглядит как PI, но обрабатывается особым образом и не вызывает этот обработчик.

Синтаксис

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

xml_set_processing_instruction_handler($parser, $handler)

Где $parser — это ресурс XML-парсера, возвращённый функцией xml_parser_create(), а $handler — вызываемый объект или строка с именем пользовательской функции, которая будет обрабатывать инструкции обработки. Передайте пустую строку ("") для удаления ранее зарегистрированного обработчика.

Параметры

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

Возвращает true в случае успеха или false, если $parser не является допустимым XML-парсером.

Сигнатура обработчика

Ваш обработчик вызывается ровно с тремя аргументами:

function handler($parser, string $target, string $data): void

• $parser — парсер, который запустил обратный вызов.
• $target — цель PI (имя сразу после <?).
• $data — остальная часть PI в виде необработанной строки. Вы сами несёте ответственность за её разбор; XML-парсер не разбивает её на атрибуты.

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

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

Пример: Установка функции-обработчика инструкций обработки

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

function handle_processing_instruction($parser, $target, $data) {
    echo "Processing instruction found: $target - $data\n";
}

$xml_parser = xml_parser_create();
xml_set_processing_instruction_handler($xml_parser, "handle_processing_instruction");

$xml_data = '<?xml version="1.0"?><root><?PI target data?></root>';
if (!xml_parse($xml_parser, $xml_data)) {
    echo "XML parse error: " . xml_error_string(xml_get_error_code($xml_parser));
}

xml_parser_free($xml_parser);

Этот код создаёт новый парсер с помощью xml_parser_create(). Затем он устанавливает пользовательскую функцию для обработки инструкций обработки. Функция xml_parse() обрабатывает XML-строку, вызывая обработчик при обнаружении инструкции обработки. Возвращаемое значение проверяется, чтобы xml_error_string() мог сообщить об ошибках разбора. Наконец, xml_parser_free() освобождает ресурс парсера после использования.

В PHP 7.4 программа выводит:

Processing instruction found: PI - target data

Пример: Разбор данных PI в параметры

Данные PI поступают в виде одной необработанной строки, поэтому любая структура внутри неё остаётся на ваше усмотрение. Распространённый подход — обрабатывать данные как пары key="value":

function pi_handler($parser, $target, $data) {
    // Pull out key="value" pairs from the PI data
    preg_match_all('/(\w+)="([^"]*)"/', $data, $pairs, PREG_SET_ORDER);
    $options = [];
    foreach ($pairs as $pair) {
        $options[$pair[1]] = $pair[2];
    }
    echo "Target: $target\n";
    print_r($options);
}

$parser = xml_parser_create();
xml_set_processing_instruction_handler($parser, "pi_handler");
xml_parse($parser, '<root><?cache ttl="60" scope="page"?></root>');
xml_parser_free($parser);

В PHP 7.4 это выводит:

Target: cache
Array
(
    [ttl] => 60
    [scope] => page
)

Связанные обработчики

xml_set_processing_instruction_handler() — одна из семейства функций установки SAX-обработчиков. Обычно вы регистрируете несколько из них одновременно на одном парсере:

• xml_set_element_handler() — открывающие и закрывающие теги.
• xml_set_character_data_handler() — текст между тегами.
• xml_set_default_handler() — всё, что не перехвачено другими обработчиками.
• xml_set_object() — маршрутизация обработчиков к методам объекта вместо обычных функций.

Типичные подводные камни

• XML-объявление не является PI здесь. <?xml ... ?> потребляется парсером и никогда не достигает вашего обработчика.
• Данные не разобраны. $data — это единая строка. Парсер не разбивает содержимое key="value" на атрибуты — разбирайте его самостоятельно.
• Обработчик устанавливается до разбора. Регистрируйте обработчик перед вызовом xml_parse(), иначе ранние инструкции будут пропущены.
• PHP 8.2+ не имеет расширения xml. Все функции xml_* удалены; примеры на этой странице работают только на PHP 7.4 и более ранних версиях.

Заключение

В этой статье мы рассмотрели функцию PHP xml_set_processing_instruction_handler() и то, как она используется для установки обработчика инструкций обработки в XML-парсере устаревшего расширения xml. Мы объяснили её синтаксис и привели практический пример. Поскольку расширение xml было удалено в PHP 8.2, современные приложения должны предпочитать XMLReader или DOMDocument для обработки XML. Для устаревших кодовых баз на PHP 7.4 и более ранних версиях эта функция остаётся надёжным способом обработки инструкций обработки в процессе SAX-разбора.

Практика