xml_parser_set_option()

The xml_parser_set_option() function is a PHP built-in function that sets configuration options on an XML parser. It belongs to the legacy XML Parser (Expat) extension, which parses XML in a SAX style — firing event callbacks as it reads — rather than building an in-memory tree like SimpleXML or DOM. You call it after xml_parser_create() but before parsing, to control how the parser treats tag-name case, whitespace, and character encoding.

Syntax

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

• $parser — the parser returned by xml_parser_create(). Since PHP 8.0 this is an XMLParser object; in PHP 7 and earlier it was a resource.
• $option — one of the option constants below.
• $value — the value to set for that option.

The function returns true on success, or false if the parser or option is invalid.

Available options

Read the current value with xml_parser_get_option(). Setting an option after parsing has begun has no effect, so configure the parser first.

Why case folding matters

This is the option you will reach for most often. By default the parser upper-cases every tag name, so an element <note> arrives in your handler as NOTE. That surprises people who compare names against lowercase strings. Turning case folding off keeps names exactly as written:

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

Output:

Start: NOTE
Start: TO

Set XML_OPTION_CASE_FOLDING to false and the same input keeps its original case (note, to).

A complete example

The XML Parser extension is event-driven: nothing happens until you register handlers and feed it data. This example creates a parser, sets two options, registers start/end handlers, and parses an inline XML string — no external file required, so you can run it as-is:

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

Output:

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

Because case folding is off, the tag names keep their lowercase spelling. The xml_set_element_handler() call is what lets xml_parse() emit these events; without registered handlers the parser would read the document but produce no output. Always call xml_parser_free() when you are done to release the parser.

When to use it

Use xml_parser_set_option() only when you are already working with the low-level Expat parser — typically for streaming very large XML documents where loading the whole tree into memory is undesirable. For most everyday tasks (reading config, consuming an API response) reach for SimpleXML instead, which is far simpler and needs none of this configuration.

Conclusion

xml_parser_set_option() configures the legacy SAX-style XML parser — most importantly its case-folding, whitespace, and encoding behaviour. Set every option before calling xml_parse(), register element handlers so events are emitted, and free the parser afterwards. When you need fine-grained, memory-efficient streaming this function gives you that control; otherwise SimpleXML or DOM are the easier choice.

Practice