Error Reporting

PHP has a configurable error reporting system that you can set to be just as pedantic you want it to be about code. By default, the strictest mode is not enabled, and, in most cases, you get a warning message only when an imperfection has a good chance of affecting the intended purpose of your script.

Changing Error Levels

To change the error reporting level, you use the error_reporting function with a value that is made up of the constants shown in Table 22.1.

Table 22.1. Error Reporting Constants

Constant	Description
E_ERROR	Indicates a fatal runtime error. Script execution is halted.
E_WARNING	Issues runtime warnings. Non-fatal; script execution continues.
E_PARSE	Indicates compile-time parsing errors.
E_NOTICE	Issues runtime notices, which may or not indicate errors.
E_CORE_ERROR	Issues a fatal error generated internally by PHP.
E_CORE_WARNING	Issues a warning generated internally by PHP.
E_COMPILE_ERROR	Issues a fatal error generated by the Zend engine.
E_COMPILE_WARNING	Issues a warning generated by the Zend engine.
E_USER_ERROR	Issues a user-generated error message, triggered by trigger_error.
E_USER_WARNING	Issues a user-generated warning, triggered by TRigger_error.
E_USER_NOTICE	Issues a user-generated notice, triggered by trigger_error.
E_ALL	Issues all errors and warnings except E_STRICT.
E_STRICT	Issues all errors and warnings, plus PHP suggests code changes to improve code compatibility.

You combine these constants by using bitwise operators to create a bitmask that represents the desired level. The default value is E_ALL & ~E_NOTICE, which means that all errors and warnings are displayed except for E_STRICT, which is not covered by E_ALL, and E_NOTICE.

To set the error reporting level so that all warnings and notices are displayed, you use the following command:

 error_reporting(E_ALL); 

The type of notices that are not displayed by default are not life-threatening and do not affect the normal execution of a script.

The E_NOTICE error level can be very useful during script development because it alerts you to the use of undefined variables. Although using E_NOTICE does not cause an error in your script, seeing these warnings can often alert you to an identifier name that was mistyped and should be referencing a previously declared value.

When you use E_NOTICE, you are also warned about certain points of coding style. For instance, array key identifiers should be enclosed in quotation marks, but a sloppy programmer might use $array[key]. PHP first assumes that key is a constant, but if no constant with that name is defined, it also tries to use it as a string key name. With E_NOTICE enabled, you are advised of this ambiguity.

The E_STRICT level is new in PHP 5, and it is useful if you want to make sure your code is up-to-date. It warns you if you use deprecated functions that have been left in the PHP language for backward compatibility.

You can also set the error reporting level in the php.ini file, or per directory, by using .htaccess, using the error_reporting directive. Lesson 23, "PHP Configuration," describes how to use these features.

Displaying Errors The log_errors and display_errors configuration directives allow you to choose whether errors and warnings are displayed to screen or written to a log file.

On a production web site, you should consider whether displaying error messages onscreen is a security risk because it could convey information about your system to an intruder or a competitor.

Custom Error Handlers

PHP allows you to define a custom function that is called whenever an error is encountered. This replaces the default action of displaying the error message to screen or logging to a file, depending on your configuration.

You use the set_error_handler function to declare which function should be used as the custom error handler. Its first argument is the function name, and you can give an optional second argument that contains a bitmask that specifies which error levels should be handled by that function.

For example, to use the function myhandler to trap all E_WARNING and E_NOTICE errors, you use the following command:

 set_error_handler("myhandler", E_WARNING & E_NOTICE); 

The user-defined error handler function requires two parameters: an error code number and a string error message. The error code value can be compared to the constants in Table 22.1 to find out what type of error occurred. You can include three more optional parameters if you want to process the information they pass to the function: the filename, line number, and context when the error occurred.

The example in Listing 22.1 declares a custom error handler function that logs all errors to a MySQL database table.

Listing 22.1. Writing a Custom Error Handler

 <?php function log_errors($errno, $errstr, $errfile, $errline) {   $db = mysql_connect("localhost", "loguser", "logpassword");   mysql_select_db("test", $db);   $errstr = mysql_escape_string($errstr);   $sql = "insert into php_log              (errno, errstr, errfile, errline)           values              ('$errno', '$errstr', '$errfile', '$errline')";   $res = mysql_query($sql, $db); } set_error_handler("log_errors"); // Assigning an undefined variable will raise a warning $a = $b; ?> 

You create the database table required to log these errors by using the following SQL statement:

 CREATE TABLE php_log (   error_timestamp timestamp,   errno int,   errstr text,   errfile text,   errline int ); 

Note that this example does not use the optional fifth parameter that passes in the context. The context is passed as an array that contains the contents of every variableboth local values and system super-globalsin the script at the time the error occurred.

Although this information can sometimes be useful when you're debugging, it is a lot of information to store to a log file or table. Furthermore, because the value passed is an array, you need to pass $errcontext through the serialize function in order to store it to a database or text file.

Context Data Most likely you are interested in only a small part of the context data passed to your error handler function, so you can have the function extract as much information as is necessary and discard the rest.

Raising User Errors

You can use the trigger_error function to raise an error on demand. If a custom error handler has been defined, it handles this user error. Otherwise, the default PHP error handler takes the appropriate action.

You should pass an error message string to the TRigger_error function, and you can optionally give an error type constant. If no error type is given, E_USER_NOTICE is used.

For example, to raise a user notice type, you use this statement:

 trigger_error("Some kind of error happened"); 

The error message displayed will look similar to the following:

 Notice: Some kind of error happened in /home/chris/error.php on line 3 

To raise an error with the same message text but as a fatal error, you use this statement instead:

 trigger_error("Some kind of error happened", E_USER_ERROR); 

Error Types You have to use the E_USER_ERROR and E_USER_WARNING types, not E_ERROR and E_WARNING, for user errors. An E_USER_ERROR type error is still treated as a fatal error, however, and script execution ends immediately when it occurs.

Logging Errors

You can accomplish most simple error logging requirements by using the error_log function. You can use this function to write an error message to the web server log file or some other local file, send it via email, or transmit it to a remote debugging service.

The error_log function takes the following arguments:

 error_log($message, $message_type, $destination,             $extra_headers); 

Only the message argument is required, and the default action is to write this message text to the usual PHP log file. In most cases, this is your web server's log file.

The message_type argument specifies a number that determines what type of destination is supplied. Its possible values are shown in Table 22.2.

Table 22.2. message_type Argument Values in error_log

Value	Description
0	The message will be written to the default web server log file.
1	The message will be sent via email; destination contains the address to send to, and exTRa_headers contains optional email headers.
2	The message will be sent to a remote debugging service; destination contains the remote hostname. Note that remote debugging is not available in PHP 4 and later.
3	The message will be appended to a local file; destination contains the filename and path.

For example, to send an error message via email, you might use the following statement:

 error_log("An error occurred in your script", 1,           "[e-mail]",           "From: PHP Script Error <[e-mail]>"); 

Suppressing Errors and Warnings

PHP allows you to suppress warning messages in your script. You can either turn off warnings completely or select individual commands for which any errors will not be displayed.

The Error Suppression Operator

If you want to stop a warning message from appearing for a particular statement only, you can use the @ symbol to silence it. You might want to do this so that your custom error messages are displayed.

For example, when you connect to a MySQL database, PHP raises its own error if the connection fails. You can also detect the failure by checking whether a valid database resource handle was returned. The following code uses the @ symbol to suppress the PHP error message so that only your message is displayed onscreen:

 $db = @ mysql_connect("localhost", "username", "password"); if (!$db) {   echo "Database connection failed";   exit; } 

You can place the @ symbol before any expression in PHP. It causes any error messages generated as a result of that expression being evaluated to be ignored.

In the preceding example, the expression being silenced is the database connection attempt. As a general rule, if something in PHP has a value, it can be prefixed with the @ symbol. You cannot prepend an @ symbol to a language construct such as a function definition or conditional statement.

Parsing Errors The @ operator does not hide error messages caused by parsing errors in script.

The following statement is also valid, although it does not make it clear that you are expecting the error message to originate with mysql_connect:

 @ $db = mysql_connect("localhost", "username", "password"); 

Error Suppression If you have used set_error_handler to specify a custom error handler in your script, the @ operator will have no effect.

Preventing Error Display

The configuration directive display_errors can be set to Off in php.ini to prevent any errors from being displayed onscreen. You will learn how to change the value of php.ini settings in Lesson 23.

If you choose to prevent error display for your whole website this way, you should turn on the log_errors setting so that errors and warnings are written to a file; otherwise, you will have no way of knowing about potential problems. You should not consider turning display_errors off while a website is in development.