PHP xml_set_processing_instruction_handler() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
XML Parser

Definition

In PHP, xml_set_processing_instruction_handler() registers the function that runs when the XML parser meets a processing instruction.

A processing instruction is a note for the program that reads the XML, written as <?target data?>. For example <?cache ttl=60?> has the target cache and the data ttl=60. The XML declaration at the top of a file is not a processing instruction.

Syntax

Call xml_set_processing_instruction_handler() with the values you need. Start with this line.

PHP
xml_set_processing_instruction_handler($parser, function (XMLParser $parser, string $target, string $data) {
    echo $target, ' => ', $data, PHP_EOL;
});
CallWhat it does
xml_set_processing_instruction_handler($parser, 'onPi')Uses the global function onPi() for each processing instruction.
xml_set_processing_instruction_handler($parser, [$reader, 'pi'])Uses the pi() method of the $reader object.
xml_set_processing_instruction_handler($parser, fn ($p, $t, $d) => print($t))Uses a short arrow function that prints the target.

Your handler is called as handler(XMLParser $parser, string $target, string $data). The target is not changed to uppercase, even when case folding is on. Processing instructions are uncommon, so beginners can usually rely on the element and character data handlers alone.

Library declarations
PHP
xml_set_processing_instruction_handler(XMLParser $parser, callable $handler): true

Parameters

ParameterDescription
parserRequired. The XMLParser object created by xml_parser_create() or xml_parser_create_ns().
handlerRequired. A callable that receives the parser, the target name, and the data text.

Return Value

Return ValueDescription
trueAlways returns true after the handler is stored.

PHP Examples

Example 1 — Read One Processing Instruction

Print the target and the data of a processing instruction placed inside a tiny document.

PHP
<?php
$xml = '<doc><?app mode="fast"?><a/></doc>';

$parser = xml_parser_create();

xml_set_processing_instruction_handler(
    $parser,
    function (XMLParser $p, string $target, string $data) {
        echo 'Target: ', $target, PHP_EOL;
        echo 'Data: ', $data, PHP_EOL;
    }
);

xml_parse($parser, $xml, true);

How It Works

  1. The document contains one processing instruction with the target app.
  2. Everything after the target and a space is the data, here mode="fast".
  3. The parser calls the handler as soon as it reads the instruction.
  4. The handler prints the target and the data on separate lines.

Example 2 — The XML Declaration Is Not Included

A file that starts with an XML declaration still reports only its real processing instructions.

PHP
<?php
$xml = '<?xml version="1.0"?><doc><?cache ttl=60?></doc>';

$found = [];
$parser = xml_parser_create();

xml_set_processing_instruction_handler(
    $parser,
    function (XMLParser $p, string $target, string $data) use (&$found) {
        $found[] = $target . ' => ' . $data;
    }
);

xml_parse($parser, $xml, true);

echo 'Count: ', count($found), PHP_EOL;
echo $found[0], PHP_EOL;

How It Works

  1. The string begins with an XML declaration that looks a bit like a processing instruction.
  2. The parser treats that declaration as part of the XML syntax and does not call the handler for it.
  3. Only the cache instruction inside the doc element reaches the handler.
  4. The array holds a single item, so count() prints 1.

Example 3 — Instructions Before and Inside the Root

Processing instructions can appear before the root element as well as inside it. Both are reported in document order.

PHP
<?php
$xml = '<?first x?><doc><?second y?></doc>';

$parser = xml_parser_create();

xml_set_processing_instruction_handler(
    $parser,
    function (XMLParser $p, string $target, string $data) {
        echo $target, ': ', $data, PHP_EOL;
    }
);

xml_parse($parser, $xml, true);

How It Works

  1. The first instruction sits before the doc element in the prolog.
  2. The second instruction sits inside the doc element.
  3. The parser reads the string from left to right and calls the handler for each instruction in that order.
  4. The handler prints the target and the data, so first is shown before second.

Frequently Asked Questions

It registers the function that the XML parser calls for each processing instruction, such as <?cache ttl=60?>. The function receives the target and the data.
It is an instruction for the program that reads the XML, written as <?target data?>. It is not part of the document content itself.
No. The line <?xml version="1.0"?> is the XML declaration, and the parser does not pass it to the processing instruction handler.
No. The target and data arrive exactly as written, even when XML_OPTION_CASE_FOLDING is on for tag names.
Usually not. Most scripts only need xml_set_element_handler() and xml_set_character_data_handler(). Use this handler only if your XML files contain processing instructions you care about.

Next: xml_set_start_namespace_decl_handler()

xml_set_start_namespace_decl_handler() registers the function that runs when an XML namesp.

xml_set_start_namespace_decl_handler() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful