PEAR::setErrorHandling()

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);
?>