PHP xml_set_character_data_handler() Function

---

---

The PHP XML Parser xml_set_character_data_handler() function is a built-in method which is used to operate with the text that is encased in XML tags when processing the document. You can write a custom function to deal with this text data. This makes working with XML files and extracting the required material much easier. It allows data management and reading across XML elements.

Note: This function tells the parser which function to call when it finds character data in the XML file. The handler parameter can also be an array containing an object reference and the method name.

Syntax

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

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

Parameters

Here are the parameters of the xml_set_character_data_handler() function −

• $xml_parser: (Required) It is used to specify the XML parser to use.

• $handler: (Required) It specifies the function or method that the XML parser will call in response to certain events, like encountering character data in an XML document.

The $handler's behavior is determined by its type and value −

• If handler is null: By passing null, any previously set custom handler is essentially removed and the handler is returned to its default state.

• If handler is an empty string (""): This also returns the handler to its initial state; however, PHP 8.4.0 deprecates this behavior, therefore it should not be used.

• If handler is a callable: The handler is assigned to the given callable. It is suggested to specify a custom handler in this case.

• If handler is a string referring to a method name: If handler is a string that points to a method name, it must point to an object's method that was set with xml_set_object().

Return Value

The xml_set_character_data_handler() function returns different values depending on whether or not the $option parameter is used. And FALSE on failure.

Warning

This method is no longer supported as of PHP 8.4.0. In PHP 8.4.0 and later, the reliability of the callable is checked when the handler is set (instead of when it is called). Therefore, xml_set_object() must be executed before setting the handler as a method string.

PHP Version

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

Example 1

First we will show you the basic example of the PHP XML Parser xml_set_character_data_handler() function. This example parses a simple XML string and prints the character data inside the XML tags with the help of a custom handler function called character_data_handler().

<?php
   // Sample XML string
   $xml_data = '<root><name>Aditya</name><age>30</age></root>';

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

   // Define the handler function
   function character_data_handler($parser, $data) {
      
      // Print the character data
      echo "Data: $data\n";  
   }

   // Set the character data handler
   xml_set_character_data_handler($parser, 'character_data_handler');

   // Parse the XML string
   xml_parse($parser, $xml_data);
   xml_parser_free($parser);
?>

Output

Here is the outcome of the following code −

Data: Aditya
Data: 30

Example 2

In the below PHP code we will use the xml_set_character_data_handler() function to extract specific data. This example shows how to use the character data handler to search for set text, in this case the name "Deepak". If it is found, it prints it.

<?php
   $xml_data = '<person><name>Deepak</name><age>25</age></person>';

   $parser = xml_parser_create();

   function handle_name($parser, $data) {
      if (strpos($data, 'Deepak') !== false) {
         echo "Found name: $data\n";
      }
   }

   xml_set_character_data_handler($parser, 'handle_name');
   xml_parse($parser, $xml_data);
   xml_parser_free($parser);
?> 

Output

This will generate the below output −

Found name: Deepak

Example 3

In this example, the handler is an object method. The xml_set_character_data_handler() function of the XMLHandler class is called each time character data is encountered.

<?php
   class XMLHandler {
      public function character_data_handler($parser, $data) {
         // Print data processed by the method
         echo "Handled data: $data\n";  
      }
   }

   $xml_data = '<book><title>PHP Basics</title><author>Aditya Bansal</author></book>';

   $parser = xml_parser_create();
   $handler = new XMLHandler();

   // Set the handler to the object's method
   xml_set_object($parser, $handler);
   xml_set_character_data_handler($parser, array($handler, 'character_data_handler'));

   xml_parse($parser, $xml_data);
   xml_parser_free($parser);
?> 

Output

This will create the below output −

Handled data: PHP Basics
Handled data: Aditya Bansal