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).

Easy to distinct basic PEAR_Error from other PEAR packages to HTML_CSS errors, even if there is a better and more robust solution: HTML_CSS::isError(). But also provide a unique way to retrieve the level of error (warning, error, exception) with the HTML_CSS_Error::getLevel() method.

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

and output to screen will give something like :

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)

HTML_CSS obey at display_errors and log_errors protocol

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

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.

If you want to ignore all errors raised (no display, no logs) and avoid to include PEAR core class, then you should have something like :

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

function myErrorHandler()
{
    return null;
}

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

Note for users of HTML_CSS 1.4.0 or greater

You may want to decide to print (yes/no), log (yes/no) error messages with a full free user function local to HTML_CSS

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

function myErrorAction($css_error)
{
    // do what you want: print and/or log $css_error instance of HTML_CSS_Error object
}

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

rather than using global PEAR error handler (PEAR::setErrorHandling, PEAR::pushErrorHandling, PEAR::popErrorHandling).

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

function myErrorAction($css_error)
{
    // do what you want: print and/or log $css_error instance of HTML_CSS_Error object
}

PEAR::setErrorHandling(PEAR_ERROR_CALLBACK, 'myErrorAction');

$css = new HTML_CSS();
// ...
?>

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.

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.

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"*********
     

To have both display and log output, check the php.ini display_errors and log_errors values : must be set to TRUE.

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

are redefined, thats means remains key

• eol

keep its default value. See table below.

If you don't wish to see context information in the error message, then remove the parameter %3$ in the lineFormat option even if contextFormat is set.

Review now the log driver custom values. Only two keys

• lineFormat
• timeFormat

are redefined, thats means six remains keys

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

keep their default values. See table below.

If you don't wish to see context information in the error message, then remove the parameter %5$ in the lineFormat option even if contextFormat is set.

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):