PHP xml_set_external_entity_ref_handler() Function

---

---

The PHP XML Parser xml_set_external_entity_ref_handler() function is used to set a user-defined function as the handler for external entity references in an XML parser. This method is used to set a custom function to handle external entity references when processing XML files with the SimpleXML library or other PHP XML parsing libraries.

For managing external entities referenced in an XML file, like importing external data from a database or performing other tasks, the xml_set_external_entity_ref_handler() function is helpful.

Syntax

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

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

Parameters

Here are the parameters of the xml_set_external_entity_ref_handler() function −

• $xml_parser: (Required) It is the name of the user-defined function that will handle references to external entities.

• $handler: (Required) It is the XML parser that the handler is set on.

Handler Signature

The signature of the handler is as follows −

bool handler(
   XMLParser $xml_parser,
   string $open_entity_names,
   string|false $base,
   string $system_id,
   string|false $public_id
)

• $xml_parser: It is the XML parser that calls the handler is contained in the variable $parser.

• $open_entity_names: It is a variable that holds the external entity's name.

• $base: The base used to resolve the external entity's system identifier (system_id). At the moment, this string is always empty.

• $system_id: It is the entity declaration's specified system identifier.

• $public_id: It is the entity declaration's selected public identifier.

Return Value

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

PHP Version

First introduced in core PHP 4, the xml_set_external_entity_ref_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_external_entity_ref_handler() function. This program offers an overview of how to create a handler function to manage external entity references. The handler just outputs the name of the external entity each time it is mentioned in the XML document.

<?php
   // Define a simple handler function
   function external_entity_handler($xml_parser, $open_entity_names, $base, $system_id, $public_id) {
      echo "External entity reference: $open_entity_names\n";
      
      // Return true to continue parsing
      return true; 
   }

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

   // Set the external entity handler
   xml_set_external_entity_ref_handler($xml_parser, 'external_entity_handler');

   // Parse a sample XML document
   xml_parse($xml_parser, '<!DOCTYPE root [ >!ENTITY test SYSTEM "test.txt"< ]><root>&test;</root>');

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

Output

Here is the outcome of the following code −

External entity reference: test

Example 2

This example shows how to handle errors using the handler function xml_set_external_entity_ref_handler(). It checks to see if the external entity file is there before processing. It prints an error message and returns false to stop further parsing if the file is missing.

<?php
   // Define a handler function 
   function handle_external_entities($xml_parser, $open_entity_names, $base, $system_id, $public_id) {
      if (!file_exists($system_id)) {
         echo "Error: External entity '$open_entity_names' not found.\n";
         // Return false to stop the parser on error
         return false; 
      }
      echo "Entity '$open_entity_names' is valid.\n";
      return true;
   }

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

   // Set the handler function
   xml_set_external_entity_ref_handler($xml_parser, 'handle_external_entities');

   // Parse the XML document
   xml_parse($xml_parser, '<!DOCTYPE root [ <!ENTITY missingEntity SYSTEM "missing.txt"> ]><root>&missingEntity;</root>');

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

Output

This will generate the below output −

Error: External entity 'missingEntity' not found.

Example 3

This example handles a large number of external entities and saves their details, like name, system ID, and public ID, to a file called external_entities.log. It also checks the external entity's integrity and properly fetches its contents. If the entity cannot be found, a warning is displayed.

<?php
   // Define a complex handler
   function complex_external_entity_handler($xml_parser, $open_entity_names, $base, $system_id, $public_id) {
      // Log entity information to a file
      $logMsg = "Entity: $open_entity_names\nSystem ID: $system_id\nPublic ID: $public_id\n";
      file_put_contents('external_entities.log', $logMsg, FILE_APPEND);

      // Return the content 
      echo "Processing entity '$open_entity_names'...\n";
      if (file_exists($system_id)) {
         return file_get_contents($system_id);
      } else {
         echo "Warning: Entity '$open_entity_names' not found!\n";
         return false;
      }
   }

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

   // Set the handler
   xml_set_external_entity_ref_handler($xml_parser, 'complex_external_entity_handler');

   // Parse an XML document 
   $xml_data = '<!DOCTYPE root [
      <!ENTITY firstEntity SYSTEM "first.txt">
      <!ENTITY secondEntity SYSTEM "second.txt">
   ]>
   <root>&firstEntity;&secondEntity;</root>';
   xml_parse($xml_parser, $xml_data);

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

Output

This will create the below output −

Processing entity 'firstEntity'...
Warning: Entity 'firstEntity' not found!