PHP xml_parser_set_option() Function

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

Definition

In PHP, xml_parser_set_option() changes a setting on an XML parser, such as case folding, tag-start skipping, whitespace skipping, or the target encoding.

Call it after xml_parser_create() and before xml_parse(). By default PHP turns every tag name into UPPERCASE for your handlers. With this function you can switch that off, trim a fixed prefix from tag names, or choose the encoding used for text passed to your handlers.

Syntax

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

PHP
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, false);
CallWhat it does
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, false)Keeps tag and attribute names exactly as written instead of turning them into uppercase.
xml_parser_set_option($parser, XML_OPTION_SKIP_TAGSTART, 2)Removes the first 2 characters from every tag name passed to your handlers.
xml_parser_set_option($parser, XML_OPTION_TARGET_ENCODING, 'ISO-8859-1')Chooses the encoding used for strings handed to your handlers.

Four options exist: XML_OPTION_CASE_FOLDING (on by default), XML_OPTION_SKIP_TAGSTART (default 0), XML_OPTION_SKIP_WHITE (default 0), and XML_OPTION_TARGET_ENCODING (UTF-8 unless you chose another one in xml_parser_create()). Use xml_parser_get_option() to read a value back.

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

Parameters

ParameterDescription
parserRequired. The XMLParser object returned by xml_parser_create() or xml_parser_create_ns().
optionRequired. One of XML_OPTION_CASE_FOLDING, XML_OPTION_SKIP_TAGSTART, XML_OPTION_SKIP_WHITE, or XML_OPTION_TARGET_ENCODING.
valueRequired. The new value. Use a bool or int for the first three options and an encoding name such as UTF-8, ISO-8859-1, or US-ASCII for the target encoding.

Return Value

Return ValueDescription
booltrue when the option was changed. In PHP 8 an unknown option or an unsupported encoding name throws a ValueError instead of returning false.

PHP Examples

Example 1 — Turn Case Folding On and Off

Collect the start-tag names from one tiny XML string, once with the default folding and once with folding switched off.

PHP
<?php
function startNames(string $xml, bool $foldCase): string
{
    $names = [];
    $parser = xml_parser_create();
    xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, $foldCase);

    xml_set_element_handler(
        $parser,
        function (XMLParser $p, string $name) use (&$names) {
            $names[] = $name;
        },
        function (XMLParser $p, string $name) {
        }
    );

    xml_parse($parser, $xml, true);
    return implode(', ', $names);
}

$xml = '<book><title>PHP</title></book>';
echo 'Folding on: ', startNames($xml, true), PHP_EOL;
echo 'Folding off: ', startNames($xml, false), PHP_EOL;

How It Works

  1. xml_parser_create() makes a fresh parser for each call of the helper.
  2. xml_parser_set_option() sets XML_OPTION_CASE_FOLDING to true or false before parsing starts.
  3. The start handler stores every tag name it receives in the names array.
  4. With folding on the names arrive in uppercase, and with folding off they keep the case from the XML.

Example 2 — Skip a Fixed Tag Prefix

Some XML files use a fixed prefix such as x_ on every tag. XML_OPTION_SKIP_TAGSTART trims that many characters from the front of each tag name.

PHP
<?php
$xml = '<x_book><x_title>PHP</x_title></x_book>';

function tags(string $xml, int $skip): array
{
    $tags = [];
    $parser = xml_parser_create();
    xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, false);
    xml_parser_set_option($parser, XML_OPTION_SKIP_TAGSTART, $skip);

    xml_set_element_handler(
        $parser,
        function (XMLParser $p, string $name) use (&$tags) {
            $tags[] = $name;
        },
        function (XMLParser $p, string $name) {
        }
    );

    xml_parse($parser, $xml, true);
    return $tags;
}

$check = xml_parser_create();
echo 'Option set: ', var_export(xml_parser_set_option($check, XML_OPTION_SKIP_TAGSTART, 2), true), PHP_EOL;
echo 'Skip 0: ', implode(', ', tags($xml, 0)), PHP_EOL;
echo 'Skip 2: ', implode(', ', tags($xml, 2)), PHP_EOL;

How It Works

  1. The first call shows that xml_parser_set_option() returns true when the option is accepted.
  2. The tags() helper turns case folding off so the names stay in lowercase.
  3. With a skip value of 0 the handler sees the full names x_book and x_title.
  4. With a skip value of 2 the first two characters are removed, so the handler sees book and title.

Example 3 — Target Encoding and Invalid Values

Set the target encoding, read the options back, and see what happens when you pass an encoding PHP does not support.

PHP
<?php
$parser = xml_parser_create();

xml_parser_set_option($parser, XML_OPTION_TARGET_ENCODING, 'ISO-8859-1');
xml_parser_set_option($parser, XML_OPTION_SKIP_WHITE, true);

echo 'Encoding: ', xml_parser_get_option($parser, XML_OPTION_TARGET_ENCODING), PHP_EOL;
echo 'Skip white: ', xml_parser_get_option($parser, XML_OPTION_SKIP_WHITE), PHP_EOL;
echo 'Case folding: ', xml_parser_get_option($parser, XML_OPTION_CASE_FOLDING), PHP_EOL;

try {
    xml_parser_set_option($parser, XML_OPTION_TARGET_ENCODING, 'NOT-AN-ENCODING');
} catch (ValueError $e) {
    echo 'Bad encoding: ', get_class($e), PHP_EOL;
}

How It Works

  1. The target encoding is set to ISO-8859-1 and whitespace skipping is switched on.
  2. xml_parser_get_option() reads the values back, and the untouched case folding option still shows its default of 1.
  3. Passing NOT-AN-ENCODING as the target encoding is not allowed in PHP 8.
  4. PHP throws a ValueError, which the catch block reports by printing the class name.

Frequently Asked Questions

It changes one setting of an XMLParser object. You can control case folding, how many characters to skip at the start of tag names, whether whitespace-only values are skipped, and which encoding is used for text passed to your handlers.
XML_OPTION_CASE_FOLDING is on by default, so PHP converts tag and attribute names to uppercase before calling your handlers. Call xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, false) to keep the original case.
Call it after creating the parser and before the first xml_parse() call. Changing an option in the middle of a parse is not a supported way to work.
PHP supports UTF-8, ISO-8859-1, and US-ASCII as target encodings. Any other name throws a ValueError in PHP 8.
Use xml_parser_get_option() with the same XML_OPTION_* constant. It returns the current integer or string value of that option.

Next: xml_set_character_data_handler()

xml_set_character_data_handler() registers the function that receives the text found betwe.

xml_set_character_data_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