Error Handler

Introduction

The HTML_CSS package is implemented with a flexible error handler plug-in system. You may use any error handler that you want. Using PEAR_Error object (default), but also the PEAR_ErrorStack package, or any other error handler you might want to plug in.

Without any configuration, each HTML_CSS API error (basic or exception) will raise a HTML_CSS_Error object that will be return to call script (user script).

As usual you can use the PEAR error API as well.

     
<?php
require_once 'HTML/CSS.php';

$css = new HTML_CSS();

$result = $css->setStyle('div', 'color', 5);
if (PEAR::isError($result)) {
    // do something when an error is raised
}
?>


    

Exception*: invalid input, parameter #3 "$value" was expecting "string",
instead got "integer"** in html_css->setstyle (file [path_to]\[filename] on line 6)***
     

Perhaps this standard behavior is not what you want. Don't worry, you can change everything :

• display or ignore the error

• display or hide part of message (error level, body, context)

Configuring a Handler

A error handler's configuration is determined by the arguments used in its construction. Here's an overview of these parameters.

    
<?php
require_once 'HTML/CSS.php';

$errorConf = array('error_handler' => 'myErrorHandler',
                   'push_callback' => 'myError',
                   // ... more options
                  );
$css = new HTML_CSS(null, $errorConf);
?>


   

Controlling error generation

There are many scenarios in which fine-grained control over error raising is absolutely necessary.

The first level to control error generation is the php.ini directives display_errors and log_errors. When these directives are set to TRUE, then browser and file outputs are effective.

       
<?php
require_once 'HTML/CSS.php';

function myErrorHandler()
{
    return null;
}

$errorConf = array('error_handler' => 'myErrorHandler');
$css = new HTML_CSS(null, $errorConf);
// ...
?>


      

With push_callback option, you can decides to stop script execution (as done with exceptions by default: returns PEAR_ERROR_DIE constant), or continue without filtering (returns NULL).

If you want to write your own callback function for the push_callback option, this one should have two arguments: first one will get the error code, and second will get error level. These are all the necessary informations to do a filtering. Example that follow show how to be aware that a script use wrong argument data type.

     
<?php
require_once 'HTML/CSS.php';

function myErrorFilter($code, $level)
{
    if ($code === HTML_CSS_ERROR_INVALID_INPUT) {
        error_log('script: '.__FILE__.' used wrong argument data type', 1, 'admin@yoursite.com');
    }
    return null;
}

$errorConf = array('push_callback' => 'myErrorFilter');
$css = new HTML_CSS(null, $errorConf);
// ...
?>


    

Error Context Display

In some cases, you may want to customize error generation. For instance, for each error (basic/exception), it is useful to include file, line number, and class/function context information in order to trace it. The default option will be sufficient for most cases but you want perhaps customize the output format (render) of context information.

With this example we will change display and log renders.

     
<?php
require_once 'HTML/CSS.php';

$displayConfig = array(
    'lineFormat' => '<b>%1$s</b>: %2$s<br />%3$s',
    'contextFormat' =>   '<b>File:</b> %1$s <br />'
                       . '<b>Line:</b> %2$s <br />'
                       . '<b>Function:</b> %3$s '
);
$logConfig = array(
    'lineFormat' => '%1$s %2$s [%3$s] %4$s',
    'timeFormat' => '%b'
);

$prefs = array(
    'handler' => array('display' => $displayConfig,
                       'log'     => $logConfig
));

$css = new HTML_CSS(null, $prefs);
// ...
$result = $css->setStyle('div', 'color', 5);
?>


    

Display render will give something like:

Exception****: invalid input, parameter #3 "$value" was expecting "string", instead got "integer"*****
File: [path_to]\[filename] ******
Line: 22 
Function: html_css->setstyle 
     

Log render will give something like:

Jun 127.0.0.1******* [exception********] invalid input, parameter #3 "$value" was expecting "string", instead got "integer"*********
     

Let review, step by step, how to get such results.

Remember that with default classes, there are two drivers : display and log that have both their own configuration parameters. You can override these parameters values with the handler entry in the hash of second argument of the HTML_CSS class constructor.

We did it here with the $prefs variable; it's a two key associative array. First key display defines the display driver values, and the second key log defines the log driver values.

Review the display driver custom values. Only two keys:

• lineFormat
• contextFormat

• eol

Review now the log driver custom values. Only two keys

• lineFormat
• timeFormat

• eol
• contextFormat
• ident
• message_type
• destination
• extra_headers

Custom Error Message Generation

There are two methods of HTML_CSS_Error designed for use with generating error messages efficiently. To use them, you must set the options below in the HTML_CSS class constructor (argument #2):

      
<?php
$messages = array(
    HTML_CSS_ERROR_UNKNOWN =>
        'unknown error',
    HTML_CSS_ERROR_INVALID_INPUT =>
        'invalid input, parameter #%paramnum% '
      . '"%var%" was expecting '
      . '"%expected%", instead got "%was%"'
);
?>