****************************
 The HTML_Progress2 Package
****************************

-------------------------------------
 User Documentation - Error Handling
-------------------------------------

:Author:        Laurent Laville
:Contact:       pear@laurent-laville.org
:Date:          $Date: 2005/06/15 06:57:31 $
:Revision:      $Revision: 1.2 $


Using error Handler
======================

The HTML_Progress2 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_Progress2 API error (basic or exception)
will raise a PEAR_Error instance that will be return to call script (user
script).

As usual you can use the PEAR error API as well:
....
::
    require_once 'HTML/Progress2.php';

    $meter = new HTML_Progress2();

    $result = $meter->setValue('37');
    if (PEAR::isError($result)) {
        // do something when an error is raised
    }
....

Output will look like:

Exception: invalid input, parameter #1 "$val" was expecting "integer",
instead got "string" in html_progress2->setvalue (file
[...path_to...]\eh.php on line 6)

You can notice the following:
- the error level:
  Exception
- the message body with context informations:
  invalid input, parameter #1 "$val" was expecting "integer", instead got
  "string"
- the context of call:
  in html_progress2->setvalue (file [...path_to...]\eh.php on line 6)

Perhaps this standard behaviour 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.
....
::
    require_once 'HTML/Progress2.php';

    $errorConf = array('error_handler' => 'myErrorHandler',
                       'push_callback' => 'myError',
                       // ... more options
                      );
    $meter = new HTML_Progress2($errorConf);
....


+--------------------+-----------+-------------------------------------------+
| Option             | Type      | Description                               |
+====================+===========+===========================================+
| `error_handler`    | callback  | A valid callback (function) to manage     |
|                    |           | errors raised by the                      |
|                    |           | HTML_Progress2::raiseError() method.      |
|                    |           | Default is: HTML_Progress2::_errorHandler |
+--------------------+-----------+-------------------------------------------+
| `push_callback`    | callback  | A valid callback (function) that decides  |
|                    |           | to following action.                      |
|                    |           | Default return: PEAR_ERROR_DIE if         |
|                    |           |     exception                             |
|                    |           | NULL otherwise                            |
+--------------------+-----------+-------------------------------------------+
| `message_callback` | callback  | A valid callback (function) to control    |
|                    |           | message generation.                       |
|                    |           | Default is:                               |
|                    |           |     HTML_Progress2_Error::_msgCallback.   |
+--------------------+-----------+-------------------------------------------+
| `context_callback` | callback  | A valid callback (function) to control    |
|                    |           | error context generation.                 |
|                    |           | Default is:                               |
|                    |           |     HTML_Progress2_Error::getBacktrace.   |
+--------------------+-----------+-------------------------------------------+

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

If you want to ignore all errors raised  (no display, no logs) and avoid to
include PEAR core class, then :
....
::
    function myErrorHandler()
    {
        return null;
    }

    require_once 'HTML/Progress2.php';

    $errorConf = array('error_handler' => 'myErrorHandler');
    $meter = new HTML_Progress2($errorConf);

....

Option : `push_callback`

The default error handling callback means that first exception will kill the
script (returns PEAR_ERROR_DIE constant) and all other error levels will
allow the script to continue normally (returns NULL).


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.

You can change default render options with something like :
....
::
    $displayConfig = array(
        'lineFormat' => '<b>%1$s</b>: %2$s<br />%3$s<hr />',
        '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
    ));

    $meter = new HTML_Progress2($prefs);

....
Default configuration options (display driver)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
TIPS: If you don't want context information to be in the error message, then
      remove the parameter %3$ in the ``lineFormat`` option even if
      ``contextFormat`` is sets.

+-------------------+-----------+---------------+---------------------------+
| Parameter         | Type      | Default       | Description               |
+===================+===========+===============+===========================+
| ``eol``           | String    | ``<br />\n``  | The end-on-line character |
|                   |           |               | sequence.                 |
+-------------------+-----------+---------------+---------------------------+
| ``lineFormat``    | String    | ``<b>%1$s</b> | Log line format           |
|                   |           | : %2$s %3$s`` | specification.            |
|                   |           |               | 1$ = error level          |
|                   |           |               | 2$ = error message (body) |
|                   |           |               | 3$ = error context        |
+-------------------+-----------+---------------+---------------------------+
| ``contextFormat`` | String    | ``in          | Context format            |
|                   |           | <b>%3$s</b>   | (class, file, line)       |
|                   |           | (file <b>%1$s | specification.            |
|                   |           | </b> on line  | 1$ = script file name     |
|                   |           | <b>%2$s</b>`` | 2$ = line in script file  |
|                   |           |               | 3$ = class/method names   |
+-------------------+-----------+---------------+---------------------------+

Default configuration options (log driver)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
TIPS: If you don't wish context information to be in the error message, then
      remove the parameter %5$ in the ``lineFormat`` option even if
      ``contextFormat`` is set.

+-------------------+-----------+---------------+---------------------------+
| Parameter         | Type      | Default       | Description               |
+===================+===========+===============+===========================+
| ``eol``           | String    | ``\n``        | The end-on-line character |
|                   |           |               | sequence.                 |
+-------------------+-----------+---------------+---------------------------+
| ``lineFormat``    | String    | ``%1$s %2$s   | Log line format           |
|                   |           | [%3$s] %4$s   | specification.            |
|                   |           |  %5$s``       | $1 = time error           |
|                   |           |               | $2 = ident (client ip)    |
|                   |           |               | $3 = error level          |
|                   |           |               | $4 = error message (body) |
|                   |           |               | $5 = error context        |
+-------------------+-----------+---------------+---------------------------+
| ``contextFormat`` | String    | ``in %3$s     | Context format            |
|                   |           | (file %1$s    | (class, file, line)       |
|                   |           | on line %2$s``| specification.            |
|                   |           |               | 1$ = script file name     |
|                   |           |               | 2$ = line in script file  |
|                   |           |               | 3$ = class/method names   |
+-------------------+-----------+---------------+---------------------------+
| ``timeFormat``    | String    | ``%b %d       | Time stamp format         |
|                   |           | %H:%M:%S``    | (for strftime_).          |
+-------------------+-----------+---------------+---------------------------+
| ``ident``         | String    | REMOTE_ADDR   | Client IP                 |
+-------------------+-----------+---------------+---------------------------+
| ``message_type``  | String    | 3             | Destination type          |
|                   |           |               | (for error_log).          |
+-------------------+-----------+---------------+---------------------------+
| ``destination``   | String    | ``html_       | Destination name          |
|                   |           | progress2_    | (for error_log).          |
|                   |           | error.log``   |                           |
+-------------------+-----------+---------------+---------------------------+
| ``extra_headers`` | String    | NULL          | Extra headers depending   |
|                   |           |               | of destination type.      |
+-------------------+-----------+---------------+---------------------------+


Custom Error Message Generation
-------------------------------
There are two methods of HTML_Progress2_Error designed for use with
generating error messages efficiently. To use them, you must set the options
below in the HTML_Progress2 class constructor (argument #1):

Option: `message_callback`

The default message handling callback get an array mapping error codes
to error message templates (HTML_Progress2_Error::_getErrorMessage) like so:
....
::
    $messages = array(
        HTML_PROGRESS2_ERROR_UNKNOWN =>
            'unknown error',
        HTML_PROGRESS2_ERROR_INVALID_INPUT =>
            'invalid input, parameter #%paramnum% '
          . '"%var%" was expecting '
          . '"%expected%", instead got "%was%"'
    );
....

Basically, if a variable name is enclosed in percent signs (%), it will be
replaced with the value passed in the associative array.

In such condition, you can change easily the message templates as you want.
For instance, you could write french messages:
....
::
    $messages = array(
        HTML_PROGRESS2_ERROR_UNKNOWN =>
            'Erreur inconnue',
        HTML_PROGRESS2_ERROR_INVALID_INPUT =>
            'entre invalide, le paramtre #%paramnum% '
          . '"%var%" contient un "%was%"; '
          . 'il devrait contenir un "%expected%"'
    );
....

Option : `context_callback`

The default context handling callback gets an array of execution functions
and discovers where the error was generated
(HTML_Progress2_Error::getBackTrace), see also PEAR core class.

