PHP xml_set_unparsed_entity_decl_handler() Function

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

Definition

In PHP, xml_set_unparsed_entity_decl_handler() registers the function that runs when the XML parser reads an unparsed entity declaration in a DTD.

An unparsed entity is a name for binary data such as an image, declared with the NDATA keyword, for example <!ENTITY logo SYSTEM "logo.gif" NDATA gif>. It is a rarely used DTD feature, and everyday XML apps mainly need the element handler and the character data handler.

Syntax

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

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

Your handler is called as handler(XMLParser $parser, string $entity_name, string|false $base, string $system_id, string|false $public_id, string $notation_name). It is called while the DTD is being read, so the XML must start with a DOCTYPE that declares an entity with NDATA.

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

Return Value

Return ValueDescription
trueAlways returns true after the handler is stored.

PHP Examples

Example 1 — Read an Unparsed Entity

Parse a tiny DTD with one notation and one unparsed entity, then print the details the handler receives.

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

$parser = xml_parser_create();

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

xml_parse($parser, $xml, true);

How It Works

  1. The DTD declares a notation named gif for the image format.
  2. It also declares an entity named logo that points to logo. gif and uses the gif notation through NDATA.
  3. The NDATA keyword makes logo an unparsed entity, so the parser calls the handler for it.
  4. The handler prints the entity name, the file, the notation, and none because no public id was given.

Example 2 — Several Unparsed Entities

The handler runs once for each unparsed entity. Collect them in an array and print a short summary line for each.

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

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

xml_set_unparsed_entity_decl_handler(
    $parser,
    function (XMLParser $p, string $name, string|false $base, string $systemId, string|false $publicId, string $notation) use (&$entities) {
        $entities[] = $name . ' (' . $notation . ') -> ' . $systemId;
    }
);

xml_parse($parser, $xml, true);

echo implode(PHP_EOL, $entities), PHP_EOL;

How It Works

  1. The DTD declares two notations and two unparsed entities.
  2. The parser calls the handler once for logo and once for photo, in document order.
  3. The handler builds a summary string from the name, the notation, and the system id.
  4. implode() prints each summary on its own line.

Example 3 — Notation and Entity Together

Use the notation handler and the unparsed entity handler together to connect each entity with its data format.

PHP
<?php
$xml = '<!DOCTYPE doc ['
    . '<!NOTATION gif SYSTEM "image/gif">'
    . '<!ENTITY logo SYSTEM "logo.gif" NDATA 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, ' = ', $systemId, PHP_EOL;
    }
);

xml_set_unparsed_entity_decl_handler(
    $parser,
    function (XMLParser $p, string $name, string|false $base, string $systemId, string|false $publicId, string $notation) {
        echo 'Entity ', $name, ' uses ', $notation, PHP_EOL;
    }
);

xml_parse($parser, $xml, true);

How It Works

  1. Both handlers are registered on the same parser before xml_parse() runs.
  2. The notation is declared first, so the notation handler prints its line first.
  3. The entity declaration comes next, so the unparsed entity handler prints its line second.
  4. Together the two lines show that logo is a gif file and that gif means image/gif.

Frequently Asked Questions

It registers the function the XML parser calls for each unparsed entity declared in a DTD, such as <!ENTITY logo SYSTEM "logo.gif" NDATA gif>.
It is a name for non-XML data, usually a binary file such as an image. It is declared with NDATA followed by the name of a notation.
It only runs for entities declared with NDATA inside a DOCTYPE. XML without a DTD, or with only normal entities, never triggers it.
The word after NDATA is the name of a notation. The notation, declared with <!NOTATION>, says what format the data has.
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.

Back to XML Parser Functions

Browse all PHP XML Parser function tutorials.

XML Parser functions →

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