Handling Errors

I l @ ve RuBoard

PHP's XSLT API includes some functions designed specifically to assist in tracking and displaying errors. Depending on your requirements, you can set up a primitive error handler to display error codes and messages with the xslt_errno() and xslt_error() functions, or define a custom error handler with the xslt_set_error_handler() function.

Primitive Error Handling with xslt_errno() and xslt_error()

The xslt_errno() function returns the error code of the last error encountered by the XSLT processor, whereas the xslt_error() function generates a corresponding human-readable error message. Both functions require, as argument, a handle representing the current XSLT processor, as defined by xslt_create() . If no argument is provided, the last XSLT error number/error string that occurred is returned.

To illustrate how this error handling works, let's take another look at our first example (see Listing 4.4), which demonstrates this technique.

Listing 4.4 Basic Error Handling

 <?php  // set the filenames  $xml_file = "list.xml";  $xslt_file = "list.xsl";  // create the XSLT processor  $xp = xslt_create() or die("Could not create XSLT processor");  // process the two files to get the desired output  if($result = xslt_process($xp, $xml_file, $xslt_file))  {       // print output        echo $result;  }  else  {       // else display error        echo "An error occurred: " . xslt_error($xp) . "(error code " . xslt_errno($xp) .  ")";  }  // free the resources occupied by the handler  xslt_free($xp);  ?> 

As you can see, this is pretty basic. If an error is encountered while xslt_process() is performing the transformation, PHP will merely display an error code and message. You can verify this by deliberately introducing an error into your XML or XSLT document (mismatched tags are always a favorite) and watching how PHP reacts.

Defining a Custom Error Handler with xslt_set_error_handler()

A more professional approach to error handling would be to define a custom error handler to resolve all errors that occur during the transformation process. And PHP allows you to do just that with its xslt_set_error_handler() function, which lets you define and use your own exception handling mechanism.

The xslt_set_error_handler() function accepts two arguments: a handle representing the current XSLT processor, as returned by xslt_create() , and the name of the function to pass all errors to.

The following code snippet illustrates this by setting the user -defined function myHandler() as the handler for all errors generated during the transformation process:

 xslt_set_error_handler($xp, "myHandler"); 

The user-defined error handler specified as the second argument to xslt_set_error_handler() must be set up to accept the following four arguments:

• Handle representing the XSLT processor

• Error level (whether notice, warning, or fatal error)

• Error code

• Array containing information on the error

Of these, the last is perhaps the most interesting. It's an associative array containing detailed information on the error, such as the type of error, the line on which it occurred, and the name of the file containing the broken code. Take a look at the following sidebar (titled "Under the Microscope") for a closer look at the contents of this array.

Under the Microscope

The associative array passed to the user-defined error handler contains error information in the form of key-value pairs. If you examine this array with print_r() , here's what you see:

 Array  (     [msgtype] => error      [code] => 2      [module] => Sablotron      [URI] =>  file:/usr/local/apache/htdocs/list.xml      [line] => 7      [msg] => XML parser error 7: mismatched tag  ) 

As Listing 4.5 demonstrates, most of this information is quite useful, and it can be combined into a fairly descriptive error message.

Listing 4.5 updates the example in Listing 4.4 to use the function customErrorHandler() as the handler for any and all errors encountered during the transformation process. A while() loop is used to iterate through the array to produce a more useful and descriptive error message.

Listing 4.5 Using a Custom Error Handler

 <?php  // set the filenames  $xml_file = "list.xml";  $xslt_file = "list.xsl";  // create the XSLT processor  $xp = xslt_create() or die("Could not create XSLT processor");  // set an error handler  xslt_set_error_handler($xp, "customErrorHandler");  // process the two files to get the desired output  $result = xslt_process($xp, $xml_file, $xslt_file);  // print output  echo $result;  // free the resources occupied by the handler  xslt_free($xp);  // custom error handler  function customErrorHandler($processor, $level, $ecode, $einfo)  {       echo "<html><head></head><body>Something bad just happened. Here's some more  information: <br>";        // iterate through error array        while(list($key, $value) = each($einfo))        {             echo "$key --> $value <br>";        }  echo "</body></html>";  }  ?> 

If you prefer, you can have the error handler return only the error message and the line number on which it occurred simply by accessing the relevant keys of the associative array. In Listing 4.5, this information is stored within the associative array $einfo , in the keys line and msg respectively (take a look at the sidebar entitled "Under The Microscope" for details).

I l @ ve RuBoard