PHP Manual
Prev |  | Next

# Chapter 15. Error Handling

There are several types of errors and warnings in PHP. They are:

Table 15-1. PHP error types

Value | Constant | Description | Note
--- | --- | --- | ---
1 | E_ERROR | fatal run-time errors |
2 | E_WARNING | run-time warnings (non fatal errors) |
4 | E_PARSE | compile-time parse errors |
8 | E_NOTICE | run-time notices (less serious than warnings) |
16 | E_CORE_ERROR | fatal errors that occur during PHP's initial startup | PHP 4 only
32 | E_CORE_WARNING | warnings (non fatal errors) that occur during PHP's initial startup | PHP 4 only
64 | E_COMPILE_ERROR | fatal compile-time errors | PHP 4 only
128 | E_COMPILE_WARNING | compile-time warnings (non fatal errors) | PHP 4 only
256 | E_USER_ERROR | user-generated error message | PHP 4 only
512 | E_USER_WARNING | user-generated warning message | PHP 4 only
1024 | E_USER_NOTICE | user-generated notice message | PHP 4 only
| E_ALL | all of the above, as supported |

The above values (either numerical or symbolic) are used to build up a bitmask that specifies which errors to report. You can use the bitwise operators to combine these values or mask out certain types of errors. Note that only '|', '~', '!', and '&' will be understood within `php.ini`, however, and that no bitwise operators will be understood within `php3.ini`.

In PHP 4, the default error_reporting setting is `E_ALL & ~E_NOTICE`, meaning to display all errors and warnings which are not E_NOTICE-level. In PHP 3, the default setting is `(E_ERROR | E_WARNING | E_PARSE)`, meaning the same thing. Note, however, that since constants are not supported in PHP 3's `php3.ini`, the error_reporting setting there must be numeric; hence, it is `7`.

The initial setting can be changed in the ini file with the error_reporting directive, in your Apache `httpd.conf` file with the php_error_reporting (php3_error_reporting for PHP 3) directive, and lastly it may be set at runtime within a script by using the error_reporting() function.

Warning
When upgrading code or servers from PHP 3 to PHP 4 you should check these settings and calls to error_reporting() or you might disable reporting the new error types, especially E_COMPILE_ERROR. This may lead to empty documents without any feedback of what happened or where to look for the problem.

All PHP expressions can also be called with the "@" prefix, which turns off error reporting for that particular expression. If an error occurred during such an expression and the track_errors feature is enabled, you can find the error message in the global variable `$php_errormsg`.

> Note: The @ error-control operator prefix will not disable messages that are the result of parse errors.

Warning
Currently the @ error-control operator prefix will even disable error reporting for critical errors that will terminate script execution. Among other things, this means that if you use @ to suppress errors from a certain function and either it isn't available or has been mistyped, the script will die right there with no indication as to why.

Below we can see an example of using the error handling capabilities in PHP. We define a error handling function which logs the information into a file (using an XML format), and e-mails the developer in case a critical error in the logic happens.

Example 15-1. Using error handling in a script
    <?php
    // we will do our own error handling
    error_reporting(0);

    // user defined error handling function
    function userErrorHandler ($errno, $errmsg, $filename, $linenum, $vars) {
        // timestamp for the error entry
        $dt = date("Y-m-d H:i:s (T)");

        // define an assoc array of error string
        // in reality the only entries we should
        // consider are 2,8,256,512 and 1024
        $errortype = array (
                    1   =>  "Error",
                    2   =>  "Warning",
                    4   =>  "Parsing Error",
                    8   =>  "Notice",
                    16  =>  "Core Error",
                    32  =>  "Core Warning",
                    64  =>  "Compile Error",
                    128 =>  "Compile Warning",
                    256 =>  "User Error",
                    512 =>  "User Warning",
                    1024=>  "User Notice"
                    );
        // set of errors for which a var trace will be saved
        $user_errors = array(E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE);

        $err = "<errorentry>\n";
        $err .= "\t<datetime>".$dt."</datetime>\n";
        $err .= "\t<errornum>".$errno."</errnumber>\n";
        $err .= "\t<errortype>".$errortype[$errno]."</errortype>\n";
        $err .= "\t<errormsg>".$errmsg."</errormsg>\n";
        $err .= "\t<scriptname>".$filename."</scriptname>\n";
        $err .= "\t<scriptlinenum>".$linenum."</scriptlinenum>\n";

        if (in_array($errno, $user_errors))
            $err .= "\t<vartrace>".wddx_serialize_value($vars,"Variables")."</vartrace>\n";
        $err .= "</errorentry>\n\n";

        // for testing
        // echo $err;

        // save to the error log, and e-mail me if there is a critical user error
        error_log($err, 3, "/usr/local/php4/error.log");
        if ($errno == E_USER_ERROR)
            mail("phpdev@mydomain.com","Critical User Error",$err);
    }

    function distance ($vect1, $vect2) {
        if (!is_array($vect1) || !is_array($vect2)) {
            trigger_error("Incorrect parameters, arrays expected", E_USER_ERROR);
            return NULL;
        }

        if (count($vect1) != count($vect2)) {
            trigger_error("Vectors need to be of the same size", E_USER_ERROR);
            return NULL;
        }

        for ($i=0; $i<count($vect1); $i++) {
            $c1 = $vect1[$i]; $c2 = $vect2[$i];
            $d = 0.0;
            if (!is_numeric($c1)) {
                trigger_error("Coordinate $i in vector 1 is not a number, using zero",
                                E_USER_WARNING);
                $c1 = 0.0;
            }
            if (!is_numeric($c2)) {
                trigger_error("Coordinate $i in vector 2 is not a number, using zero",
                                E_USER_WARNING);
                $c2 = 0.0;
            }
            $d += $c2*$c2 - $c1*$c1;
        }
        return sqrt($d);
    }

    $old_error_handler = set_error_handler("userErrorHandler");

    // undefined constant, generates a warning
    $t = I_AM_NOT_DEFINED;

    // define some "vectors"
    $a = array(2,3,"foo");
    $b = array(5.5, 4.3, -1.6);
    $c = array (1,-3);

    // generate a user error
    $t1 = distance($c,$b)."\n";

    // generate another user error
    $t2 = distance($b,"i am not an array")."\n";

    // generate a warning
    $t3 = distance($a,$b)."\n";

    ?>

This is just a simple example showing how to use the Error Handling and Logging functions.

See also error_reporting(), error_log(), set_error_handler(), restore_error_handler(), trigger_error(), user_error()

Prev | Home | Next
Features | Up | Creating and manipulating images