PHP xml_set_start_namespace_decl_handler() Function

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

Definition

In PHP, xml_set_start_namespace_decl_handler() registers the function that runs when an XML namespace declaration comes into scope.

A declaration such as xmlns:a="urn:a" connects the prefix a with the namespace URI urn:a. The parser calls your handler with both values just before it reports the element that contains the declaration. It only works with a parser created by xml_parser_create_ns().

Syntax

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

PHP
xml_set_start_namespace_decl_handler($parser, function (XMLParser $parser, string|false $prefix, string $uri) {
    echo ($prefix === false ? '(default)' : $prefix), ' = ', $uri, PHP_EOL;
});
CallWhat it does
xml_set_start_namespace_decl_handler($parser, 'onNsStart')Uses the global function onNsStart() for each declaration.
xml_set_start_namespace_decl_handler($parser, [$reader, 'nsStart'])Uses the nsStart() method of the $reader object.
xml_set_start_namespace_decl_handler($parser, fn ($p, $prefix, $uri) => print($uri))Uses a short arrow function that prints the URI.

Your handler is called as handler(XMLParser $parser, string|false $prefix, string $uri). The prefix is false for a default namespace such as xmlns="urn:feed". This is a niche handler, and everyday XML apps mainly need the element handler and the character data handler.

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

Parameters

ParameterDescription
parserRequired. An XMLParser object created with xml_parser_create_ns().
handlerRequired. A callable that accepts the XMLParser, the namespace prefix, and the namespace URI.

Return Value

Return ValueDescription
trueAlways returns true after the handler is stored.

PHP Examples

Example 1 — Print Prefix and URI

Create a namespace-aware parser and print the prefix and URI of the one declaration in a tiny document.

PHP
<?php
$xml = '<root xmlns:a="urn:a"><a:item>x</a:item></root>';

$parser = xml_parser_create_ns();

xml_set_start_namespace_decl_handler(
    $parser,
    function (XMLParser $p, string|false $prefix, string $uri) {
        echo $prefix, ' = ', $uri, PHP_EOL;
    }
);

xml_parse($parser, $xml, true);

How It Works

  1. xml_parser_create_ns() makes a parser that understands XML namespaces.
  2. The root element declares the prefix a for the URI urn:a.
  3. The parser reads the declaration and calls the handler with the prefix and the URI.
  4. The handler prints the pair as a = urn:a.

Example 2 — The Default Namespace Has No Prefix

A declaration without a prefix sets the default namespace. In that case the handler receives false for the prefix.

PHP
<?php
$xml = '<feed xmlns="urn:feed"><entry/></feed>';

$parser = xml_parser_create_ns();

xml_set_start_namespace_decl_handler(
    $parser,
    function (XMLParser $p, string|false $prefix, string $uri) {
        $label = $prefix === false ? '(default)' : $prefix;
        echo $label, ' = ', $uri, PHP_EOL;
    }
);

xml_parse($parser, $xml, true);

How It Works

  1. The feed element uses xmlns with no prefix, which declares the default namespace.
  2. The parser has no prefix to report, so it passes false as the second argument.
  3. The code compares the prefix with === false and chooses the label (default).
  4. The label and the URI are printed together.

Example 3 — Namespace-Aware or Not

Run the same document through xml_parser_create() and xml_parser_create_ns() to see that only the second one reports declarations.

PHP
<?php
$xml = '<root xmlns:a="urn:a"><item/></root>';

function countDeclarations(XMLParser $parser, string $xml): int
{
    $count = 0;

    xml_set_start_namespace_decl_handler(
        $parser,
        function (XMLParser $p, string|false $prefix, string $uri) use (&$count) {
            $count++;
        }
    );

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

echo 'xml_parser_create: ', countDeclarations(xml_parser_create(), $xml), PHP_EOL;
echo 'xml_parser_create_ns: ', countDeclarations(xml_parser_create_ns(), $xml), PHP_EOL;

How It Works

  1. The helper registers the handler on whichever parser it receives and counts the calls.
  2. A parser from xml_parser_create() does not process namespaces, so xmlns is just an attribute and the count stays 0.
  3. A parser from xml_parser_create_ns() recognizes the declaration and calls the handler once.
  4. The two printed lines show why namespace handlers need xml_parser_create_ns().

Frequently Asked Questions

It sets the function the parser calls when a namespace declaration, such as xmlns:a="urn:a", comes into scope. The function receives the prefix and the URI.
The parser must come from xml_parser_create_ns(). A parser from xml_parser_create() does not process namespaces and ignores the handler.
The prefix is false when the declaration has no prefix, such as xmlns="urn:feed". Check it with === false before using it as a string.
The namespace handler runs just before the start element handler of the element that holds the declaration, so your code knows the prefix before the tag arrives.
Usually not. Most scripts only need xml_set_element_handler() and xml_set_character_data_handler(). Namespace handlers are for tools that track prefixes and URIs.

Next: xml_set_unparsed_entity_decl_handler()

xml_set_unparsed_entity_decl_handler() registers the function that runs when the XML parse.

xml_set_unparsed_entity_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