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 ¬e; 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.
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.
The EntityResolver class stores every system id it receives in the requests array.
The handler returns true, which tells the parser that the entity was dealt with.
A callable array of the object and the method name is passed to xml_set_external_entity_ref_handler(), which returns true.
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 ¬e; 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.