PEAR Manual
Prev |  | Next

# PEAR::setErrorHandling()

PEAR::setErrorHandling() -- sets handling of errors generated through PEAR packages

## Synopsis

    require_once 'PEAR.php';

``void PEAR::setErrorHandling` ([integer $mode = `NULL` [, mixed $options = `NULL`]])`

## Description

setErrorHandling() can be invoked as both a standard object method ($obj->setErrorHandling) and as a static method (PEAR::setErrorHandling). If called statically, PEAR::setErrorHandling() sets the default error handling behaviour for all PEAR objects (global error handling behaviour). If called as an object method, $obj->setErrorHandling() sets the default error handling for only that object (local error handling behaviour).

## Parameter

- `integer $mode` - one of the following constants

  - `PEAR_ERROR_RETURN` If an error occurs, a PEAR_Error is returned from the error-generation method (normally raiseError().)

  - `PEAR_ERROR_PRINT` Like `PEAR_ERROR_RETURN`, but an error message will be printed additionally.

  - `PEAR_ERROR_TRIGGER` Like `PEAR_ERROR_RETURN`, but the PHP builtin-function trigger_error() will be called in PEAR_Error's constructor with the error message.

  - `PEAR_ERROR_DIE` The script will terminate and an error message will be printed on instantiation of a PEAR_Error.

  - `PEAR_ERROR_CALLBACK` If a error occurs, the callback passed to `$options` is called.

  - `PEAR_ERROR_EXCEPTION` If Zend Engine 2 is present, then an exception will be thrown using the PEAR_Error object.

- `mixed $options` - the value for `$options` depends on `$mode`

  - `PEAR_ERROR_PRINT` and `PEAR_ERROR_DIE` support an optional printf() format string used when printing the error message. This format string should contain a single %s, which will be used to insert the error message into the string. Use the string to enclose the error message with other useful information not included in the error message prefix or error message.

  - `PEAR_ERROR_TRIGGER` requires an user error level constant used by trigger_error() (possible constants: `E_USER_NOTICE`, `E_USER_WARNING` or `E_USER_ERROR`). Note that if the error constant is not one of these valid error constants, a PHP warning will be triggered.

  - `PEAR_ERROR_CALLBACK` The callback must be a function name in the format described in the Pseudo-Type section of the PHP manual (either a string, or an array). The callback must accept a single parameter, the PEAR_Error object generated by an error condition. Note that if the callback is not a valid callback, a PHP warning will be triggered.

Here's an example of a few ways to use setErrorHandling:

    <?php
    require_once 'PEAR.php';
    // dummy error constant for this example
    define('MYCLASS_ERROR_CODE', 1);

    // demonstration of default global error handling
    // in this case, all PEAR Errors will trigger a PHP warning
    PEAR::setErrorHandling(PEAR_ERROR_TRIGGER, E_USER_WARNING);
    // Note that the file and line number will be in the constructor of PEAR_Error
    // in PEAR.php
    PEAR::raiseError('test warning', MYCLASS_ERROR_CODE);

    // this error specifies a mode, and overrides the default global error handling
    $e = PEAR::raiseError('return only', MYCLASS_ERROR_CODE, PEAR_ERROR_RETURN);

    PEAR::setErrorHandling(PEAR_ERROR_PRINT, "Gronk error: %s<br />\n");

    // prints "Gronk error: test warning<br />\n"
    PEAR::raiseError('test warning', MYCLASS_ERROR_CODE);

    /**
     * Fake class to demonstrate error handling
     * @package myClass
     */
    class myClass extends PEAR {
        /**
         * Demonstration of default local error handling
         */
        function myClass()
        {
            // object method callback
            $this->setErrorHandling(PEAR_ERROR_CALLBACK, array(&$this, 'handleErr'));
            // prints "custom handler...is working"
            PEAR::raiseError('custom handler', MYCLASS_ERROR_CODE);
            // static class method callback
            $this->setErrorHandling(PEAR_ERROR_CALLBACK,
                array('myClass', 'handleErrStatic'));
            PEAR::raiseError('custom handler', MYCLASS_ERROR_CODE);
            // function callback
            $this->setErrorHandling(PEAR_ERROR_CALLBACK, 'standardCallback');
            PEAR::raiseError('custom handler', MYCLASS_ERROR_CODE);
        }

        /**
         * Callback set by the constructor
         * @param PEAR_Error The error object
         */
        function handleErr($error)
        {
            $this->lastError = $error->getMessage();
            print $error->getMessage() . "...is working\n";
        }

        /**
         * Static callback set by the constructor
         *
         * Note that in PHP 5, $this is not set if the method is declared with
         * the "static" access modifier.  In PHP 4, $this is set, but is not
         * set to the myClass object, so don't use it!
         * @param PEAR_Error The error object
         * @static
         */
        function handleErrStatic($error)
        {
            print 'static ' . $error->getMessage() . "...is working\n";
        }
    }

    /**
     * @param PEAR_Error The error object
     */
    function standardCallback($error)
    {
        print 'normal function callback: ' . $error->getMessage();
    }
    // This causes the printing of three messages through error callbacks:
    // "custom handler...is working"
    // "static custom handler... is working"
    // "normal function callback: custom handler"
    $mine = new myClass;

    PEAR::setErrorHandling(PEAR_ERROR_DIE);
    // terminates the script with the error message "oops"
    PEAR::raiseError('oops', MYCLASS_ERROR_CODE);
    ?>

Prev | Home | Next
PEAR::raiseError() | Up | PEAR::expectError()