PHP xml_set_external_entity_ref_handler() Function

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

Definition

In PHP, xml_set_external_entity_ref_handler() registers the function that runs when an XML document refers to an external entity declared in its DTD.

An external entity is a name that stands for content stored somewhere else, such as <!ENTITY note SYSTEM "note.xml">. When the document uses &note; the parser asks your handler to deal with it. This is an advanced feature, and everyday XML apps mainly need the element handler and the character data handler.

Syntax

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

PHP
xml_set_external_entity_ref_handler(
    $parser,
    function (XMLParser $parser, string $names, string|false $base, string $systemId, string|false $publicId): bool {
        return true;
    }
);
CallWhat it does
xml_set_external_entity_ref_handler($parser, 'onEntity')Uses the global function onEntity() for external entity references.
xml_set_external_entity_ref_handler($parser, [$resolver, 'handle'])Uses the handle() method of the $resolver object.
xml_set_external_entity_ref_handler($parser, $closure)Uses a closure stored in a variable.

Your handler is called as handler(XMLParser $parser, string $open_entity_names, string|false $base, string $system_id, string|false $public_id) and must return true when it handled the entity. Returning false, or returning nothing at all, stops the parser with an external entity error.

Library declarations
PHP
xml_set_external_entity_ref_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 open entity names, the base, the system id, and the public id. It should return true on success.

Return Value

Return ValueDescription
trueAlways returns true after the handler is stored.

PHP Examples

Example 1 — Register a Handler

Declare an external entity in a tiny DTD but never use it. The handler is registered, parsing works, and the handler is not called.

PHP
<?php
$xml = '<!DOCTYPE doc [<!ENTITY note SYSTEM "note.xml">]><doc><a>hi</a></doc>';

$calls = 0;
$text = '';
$parser = xml_parser_create();

xml_set_external_entity_ref_handler(
    $parser,
    function (XMLParser $p, string $names, string|false $base, string $systemId, string|false $publicId) use (&$calls): bool {
        $calls++;
        return true;
    }
);

xml_set_character_data_handler(
    $parser,
    function (XMLParser $p, string $data) use (&$text) {
        $text .= $data;
    }
);

$ok = xml_parse($parser, $xml, true);

echo 'Parse result: ', $ok, PHP_EOL;
echo 'Text: ', $text, PHP_EOL;
echo 'Handler calls: ', $calls, PHP_EOL;

How It Works

  1. The DTD declares an external entity named note that points to the file note. xml.
  2. The document body never writes &note;, so the parser has no reason to ask for it.
  3. xml_parse() returns 1 because the document is valid, and the character data handler collects hi.
  4. The handler is only called when the document actually refers to the entity, so the counter stays at 0.

Example 2 — Internal Entities Do Not Use the Handler

An entity with its value written inside the DTD is an internal entity. The parser expands it by itself and never calls the external entity handler.

PHP
<?php
$xml = '<!DOCTYPE doc [<!ENTITY greet "Hello">]><doc>&greet;</doc>';

$calls = 0;
$pieces = [];
$parser = xml_parser_create();

xml_set_external_entity_ref_handler(
    $parser,
    function (XMLParser $p, string $names, string|false $base, string $systemId, string|false $publicId) use (&$calls): bool {
        $calls++;
        return true;
    }
);

xml_set_character_data_handler(
    $parser,
    function (XMLParser $p, string $data) use (&$pieces) {
        $pieces[] = $data;
    }
);

xml_parse($parser, $xml, true);

echo 'Text: ', implode('', $pieces), PHP_EOL;
echo 'External handler calls: ', $calls, PHP_EOL;

How It Works

  1. The entity greet has its value Hello written directly in the DTD, so it is an internal entity.
  2. When the document uses &greet; the parser replaces it with the text Hello on its own.
  3. The character data handler receives the replacement text, and implode() joins the pieces.
  4. Only entities declared with SYSTEM or PUBLIC are external, so the external handler runs 0 times.

Example 3 — A Resolver Class

Keep the handler as a method of a small class so it can remember every system id it was asked about.

PHP
<?php
class EntityResolver
{
    public array $requests = [];

    public function handle(
        XMLParser $parser,
        string $names,
        string|false $base,
        string $systemId,
        string|false $publicId
    ): bool {
        $this->requests[] = $systemId;
        return true;
    }
}

$resolver = new EntityResolver();
$parser = xml_parser_create();

$result = xml_set_external_entity_ref_handler($parser, [$resolver, 'handle']);
echo 'Registered: ', var_export($result, true), PHP_EOL;

xml_parse($parser, '<doc>plain text</doc>', true);
echo 'Requests: ', count($resolver->requests), PHP_EOL;

How It Works

  1. The EntityResolver class stores every system id it receives in the requests array.
  2. The handler returns true, which tells the parser that the entity was dealt with.
  3. A callable array of the object and the method name is passed to xml_set_external_entity_ref_handler(), which returns true.
  4. The document has no entity references, so the requests array stays empty.

Frequently Asked Questions

It sets the function the parser calls when the document refers to an external entity, such as &note; declared with SYSTEM or PUBLIC in the DTD.
It must return true when it dealt with the entity. If it returns false or returns nothing, the parser stops with an external entity handling error.
An internal entity has its text inside the DTD, such as <!ENTITY greet "Hello">, and the parser expands it by itself. An external entity points to another file or URL with SYSTEM or PUBLIC.
Not without checks. A malicious document can point to local files or internal addresses. Only load entities from a fixed, trusted list, or simply return true and skip loading.
Usually not. Most XML reading only needs xml_set_element_handler() and xml_set_character_data_handler(). This handler is for documents that use external entities in a DTD.

Next: xml_set_notation_decl_handler()

xml_set_notation_decl_handler() registers the function that runs when the XML parser reads.

xml_set_notation_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