PHP - xml_set_unparsed_entity_decl_handler() Function

---

---

The PHP XML Parser xml_set_unparsed_entity_decl_handler() function is used to specify a handler function for unparsed entity declarations in an XML parser. This handler is triggered when the parser detects an unparsed entity in the XML data. It allows developers to handle or respond to such situations during XML processing. The function's inputs should contain the handler function's name and an XML parser resource. It is a function of the XML Parser extension for PHP that must be enabled.

Syntax

Below is the syntax of the PHP XML Parser xml_set_unparsed_entity_decl_handler() function −

true xml_set_unparsed_entity_decl_handler(XMLParser $xml_parser, callable|string|null $handler)

Parameters

Here are the parameters of the xml_set_unparsed_entity_decl_handler() function −

• $xml_parser: (Required) It is a reference to the XML parser to use inside the object.

• $handler: (Required) It is used to specifies name of function that must exist when xml_parse().

Handler Function Signature

The signature of the handler is as follows −

void handler(
   XMLParser $xml_parser,
   string $entity_name,
   string|false $base,
   string $system_id,
   string|false $public_id,
   string|false $notation_name
)

Parameters

Below are the parameters of the handler function −

• $xml_parser: Specify a variable containing the XML parser calling the handler.

• $entity_name: The name of the entity that is about to be defined.

• $base: This is a starting point for finding out the external entity's system identification (systemId).

• $system_id: It is used to identifier the external entity.

• $public_id: It is used to public identifier the external entity.

• $notation_name: It is the name of the notation of this entity.

Return Value

The xml_set_unparsed_entity_decl_handler() function returns TRUE on success. And FALSE on failure.

PHP Version

First introduced in core PHP 4, the xml_set_unparsed_entity_decl_handler() function continues to function easily in PHP 5, PHP 7, and PHP 8.

Example 1

Here is the basic example of the PHP XML Parser xml_set_unparsed_entity_decl_handler() function to set a callback handler (unparsedEntityHandler) in the event that an unparsed entity declaration is present in the XML data. The handler method will be called in order to handle any unparsed entity declarations that are found during XML parsing.

<?php
   // Define the handler function
   function unparsedEntityHandler($parser, $entity_name, $base, $system_id, $public_id, $notation_name) {
      echo "Unparsed entity: $entity_name, System ID: $system_id, Notation Name: $notation_name\n";
   }

   // Create an XML parser
   $parser = xml_parser_create();

   // Set the unparsed entity declaration handler
   xml_set_unparsed_entity_decl_handler($parser, 'unparsedEntityHandler');

   // Define an XML string 
   $xml_data = <<<XML
   <!DOCTYPE example [
      <!ELEMENT example EMPTY>
      <!ENTITY myImage SYSTEM "image.jpg" NDATA jpeg>
   ]>
   <example/>
   XML;

   // Parse the XML data
   if (!xml_parse($parser, $xml_data)) {
      echo "Error: ", xml_error_string(xml_get_error_code($parser)), "\n";
   }

   // Free the parser
   xml_parser_free($parser);
?>

Output

Here is the outcome of the following code −

Unparsed entity: myImage, System ID: image.jpg, Notation Name: jpeg

Example 2

In the below PHP code we will parse and handle multiple entities using the xml_set_unparsed_entity_decl_handler() function and show how to parse an XML document, highlighting the handler's handling of each of the unparsed entities.

<?php
   // Define the handler function
   function unparsedEntityHandler($parser, $entity_name, $base, $system_id, $public_id, $notation_name) {
      echo "Entity Name: $entity_name\nSystem ID: $system_id\nNotation: $notation_name\n---\n";
   }

   // Create an XML parser
   $parser = xml_parser_create();

   // Set the unparsed entity declaration handler
   xml_set_unparsed_entity_decl_handler($parser, 'unparsedEntityHandler');

   // Parse XML with multiple unparsed entities
   $xml_data = <<<XML
   <!DOCTYPE example [
   <!ENTITY entity1 SYSTEM "entity1.data" NDATA notation1>
   <!ENTITY entity2 SYSTEM "entity2.data" NDATA notation2>
   <!NOTATION notation1 SYSTEM "notation1.def">
   <!NOTATION notation2 SYSTEM "notation2.def">
   ]>
   <example>&entity1;&entity2;</example>
   XML;

   xml_parse($parser, $xml_data);

   // Free the parser
   xml_parser_free($parser);
?> 

Output

This will generate the below output −

Entity Name: entity1
System ID: entity1.data
Notation: notation1
---
Entity Name: entity2
System ID: entity2.data
Notation: notation2
---

Example 3

Now the below code uses the xml_set_unparsed_entity_decl_handler function. And we will un-parse entities are handled dynamically, and their data is saved in an associative array for future use.

<?php
   // Define an array 
   $unparsedEntities = [];

   // Define the handler function
   function unparsedEntityHandler($parser, $entity_name, $base, $system_id, $public_id, $notation_name) {
      global $unparsedEntities;
      $unparsedEntities[$entity_name] = [
         'base' => $base,
         'system_id' => $system_id,
         'public_id' => $public_id,
         'notation_name' => $notation_name
      ];
   }

   // Create an XML parser
   $parser = xml_parser_create();

   // Set the unparsed entity declaration handler
   xml_set_unparsed_entity_decl_handler($parser, 'unparsedEntityHandler');

   // Parse a complex XML document
   $xml_data = <<<XML
   <!DOCTYPE example [
   <!ENTITY video SYSTEM "video.mp4" NDATA video_format>
   <!ENTITY audio SYSTEM "audio.mp3" NDATA audio_format>
   <!NOTATION video_format SYSTEM "video_codec">
   <!NOTATION audio_format SYSTEM "audio_codec">
   ]>
   <media>
   <file>&video;</file>
   <file>&audio;</file>
   </media>
   XML;

   xml_parse($parser, $xml_data);

   // Display the stored entity details
   print_r($unparsedEntities);

   // Free the parser
   xml_parser_free($parser);
?> 

Output

This will create the below output −

Array
(
   [video] => Array
      (
         [base] => 
         [system_id] => video.mp4
         [public_id] => 
         [notation_name] => video_format
      )
   [audio] => Array
      (
         [base] => 
         [system_id] => audio.mp3
         [public_id] => 
         [notation_name] => audio_format
      )
)