PHP xml_set_notation_decl_handler() Function

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

Definition

In PHP, xml_set_notation_decl_handler() registers the function that runs when the XML parser reads a notation declaration in a DTD.

A notation declaration gives a name to a data format, for example <!NOTATION gif SYSTEM "image/gif">. Notations are rarely used in modern XML, and everyday XML apps mainly need the element handler and the character data handler.

Syntax

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

PHP
xml_set_notation_decl_handler(
    $parser,
    function (XMLParser $parser, string $name, string|false $base, string|false $systemId, string|false $publicId) {
        echo $name, PHP_EOL;
    }
);
CallWhat it does
xml_set_notation_decl_handler($parser, 'onNotation')Uses the global function onNotation() for each notation declaration.
xml_set_notation_decl_handler($parser, [$reader, 'notation'])Uses the notation() method of the $reader object.
xml_set_notation_decl_handler($parser, $closure)Uses a closure stored in a variable.

Your handler is called as handler(XMLParser $parser, string $notation_name, string|false $base, string|false $system_id, string|false $public_id). A missing system id or public id arrives as false. The declaration lives in the DOCTYPE, so the XML must start with a DTD for this handler to be called.

Library declarations
PHP
xml_set_notation_decl_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 notation name, the base, the system id, and the public id.

Return Value

Return ValueDescription
trueAlways returns true after the handler is stored.

PHP Examples

Example 1 — Read a SYSTEM Notation

Parse a tiny DTD with one notation and print its name and system id.

PHP
<?php
$xml = '<!DOCTYPE doc [<!NOTATION gif SYSTEM "image/gif">]><doc/>';

$parser = xml_parser_create();

xml_set_notation_decl_handler(
    $parser,
    function (XMLParser $p, string $name, string|false $base, string|false $systemId, string|false $publicId) {
        echo 'Notation: ', $name, PHP_EOL;
        echo 'System id: ', $systemId === false ? 'none' : $systemId, PHP_EOL;
    }
);

xml_parse($parser, $xml, true);

How It Works

  1. The DOCTYPE contains one notation declaration named gif.
  2. The notation points to the system id image/gif, which names the data format.
  3. While reading the DTD the parser calls the handler with the notation name and ids.
  4. The handler prints the name and the system id, using none when a value is false.

Example 2 — A PUBLIC Notation

A notation can use a public id instead of a system id. The missing system id arrives as false.

PHP
<?php
$xml = '<!DOCTYPE doc [<!NOTATION png PUBLIC "-//PNG//EN">]><doc/>';

$parser = xml_parser_create();

xml_set_notation_decl_handler(
    $parser,
    function (XMLParser $p, string $name, string|false $base, string|false $systemId, string|false $publicId) {
        echo 'Notation: ', $name, PHP_EOL;
        echo 'System id: ', $systemId === false ? 'none' : $systemId, PHP_EOL;
        echo 'Public id: ', $publicId === false ? 'none' : $publicId, PHP_EOL;
    }
);

xml_parse($parser, $xml, true);

How It Works

  1. This notation uses the PUBLIC keyword and gives only a public id.
  2. The parser has no system id for it, so the handler receives false for that argument.
  3. The code checks for false with === and prints the word none.
  4. The public id -//PNG//EN is passed as a normal string and printed.

Example 3 — List Several Notations

The handler runs once for each notation, in the order they appear in the DTD. Collect them into an array.

PHP
<?php
$xml = '<!DOCTYPE doc ['
    . '<!NOTATION gif SYSTEM "image/gif">'
    . '<!NOTATION jpeg SYSTEM "image/jpeg">'
    . ']><doc/>';

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

xml_set_notation_decl_handler(
    $parser,
    function (XMLParser $p, string $name, string|false $base, string|false $systemId, string|false $publicId) use (&$notations) {
        $notations[$name] = $systemId;
    }
);

xml_parse($parser, $xml, true);

foreach ($notations as $name => $systemId) {
    echo $name, ' => ', $systemId, PHP_EOL;
}

How It Works

  1. The DTD in this string declares two notations, gif and jpeg.
  2. The parser calls the handler once for each declaration, in document order.
  3. The handler stores the system id in an array that uses the notation name as the key.
  4. The loop prints each name with its system id.

Frequently Asked Questions

It registers the function that the XML parser calls for every <!NOTATION ...> declaration found in the DTD of a document.
A notation is a name for a data format, declared in the DTD, such as <!NOTATION gif SYSTEM "image/gif">. It is mostly used together with unparsed entities.
Notations only appear inside a DOCTYPE. If your XML has no DTD, or the DTD declares no notations, the handler stays silent.
A notation may use a public id only. When a value is missing, PHP passes false for it, so compare with === false before using it as a string.
Usually not. Everyday XML reading only needs xml_set_element_handler() and xml_set_character_data_handler(). This handler is for tools that inspect DTDs.

Next: xml_set_object()

xml_set_object() lets an XML parser use the methods of an object as handlers, so you can n.

xml_set_object() 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