xml_set_processing_instruction_handler()

The xml_set_processing_instruction_handler() function sets a user-defined function as the handler for processing instructions in an XML parser. It belongs to the legacy xml (Expat / SAX) extension and is used with event-based parsing, not with the SimpleXML library. Whenever the parser reaches a processing instruction in the document, it calls your handler so you can react to it — for example, to extract embedded directives or trigger an action mid-parse.

This page covers what processing instructions are, the function's syntax and parameters, a complete runnable example, the handler signature, common gotchas, and the modern alternatives you should reach for today.

⚠️ Deprecation Notice: The xml extension was deprecated in PHP 8.0 and completely removed in PHP 8.2. This function is only available in PHP 7.4 and earlier. For modern projects, use XMLReader or DOMDocument instead.

What Is a Processing Instruction?

A processing instruction (PI) is a special XML node that carries application-specific instructions to whatever software reads the document. It is not element content — it sits between the markup. A PI has two parts: a target (the name right after <?) and data (everything up to the closing ?>):

<?target data ?>

For example, <?php-cache ttl="60" ?> has the target php-cache and the data ttl="60". The XML declaration <?xml version="1.0"?> looks like a PI but is treated specially and does not trigger this handler.

Syntax

The syntax of the xml_set_processing_instruction_handler() function is as follows:

xml_set_processing_instruction_handler($parser, $handler)

Where $parser is the XML parser resource returned by xml_parser_create(), and $handler is a callable or a string containing the name of the user-defined function that will handle processing instructions. Pass an empty string ("") to remove a previously registered handler.

Parameters

Return Value

Returns true on success, or false if $parser is not a valid XML parser.

The Handler Signature

Your handler is called with exactly three arguments:

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

• $parser — the parser that triggered the callback.
• $target — the PI target (the name immediately after <?).
• $data — the rest of the PI, as a raw string. You are responsible for parsing it yourself; the XML parser does not split it into attributes.

Usage Examples

Let's take a look at a practical example of using xml_set_processing_instruction_handler() in PHP.

Example: Setting a Processing Instruction Handler Function

Suppose you have an XML string that contains processing instructions. You can use the xml_parser_create() function to create a new XML parser, and then set a processing instruction handler function using xml_set_processing_instruction_handler(), like this:

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

This code creates a new parser using xml_parser_create(). It then sets a custom function to handle processing instructions. The xml_parse() function processes the XML string, triggering the handler when it encounters a processing instruction. The return value is checked so xml_error_string() can report any parsing errors. Finally, xml_parser_free() cleans up the parser resource after use.

On PHP 7.4, the program prints:

Processing instruction found: PI - target data

Example: Parsing PI Data into Options

PI data arrives as one raw string, so any structure inside it is yours to parse. A common pattern is treating the data as key="value" pairs:

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

On PHP 7.4, this prints:

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

Related Handlers

xml_set_processing_instruction_handler() is one of a family of SAX handler setters. You typically register several together on the same parser:

• xml_set_element_handler() — start and end tags.
• xml_set_character_data_handler() — text between tags.
• xml_set_default_handler() — anything no other handler catches.
• xml_set_object() — route handlers to object methods instead of plain functions.

Common Gotchas

• The XML declaration is not a PI here. <?xml ... ?> is consumed by the parser and never reaches your handler.
• Data is unparsed. $data is a single string. The parser will not break key="value" content into attributes for you — parse it yourself.
• Handler set before parsing. Register the handler before calling xml_parse(), or early instructions are missed.
• PHP 8.2+ has no xml extension. All xml_* functions are gone; the examples on this page only run on PHP 7.4 or earlier.

Conclusion

In this article, we've discussed PHP's xml_set_processing_instruction_handler() function and how it can be used to set a processing instruction handler for an XML parser in the legacy xml extension. We've explained its syntax and provided a practical example. Note that because the xml extension was removed in PHP 8.2, modern applications should prefer XMLReader or DOMDocument for XML processing. For legacy codebases running on PHP 7.4 or earlier, this function remains a reliable way to handle processing instructions during SAX parsing.

Practice