PHP Error Handling

Error Handling

in a live, production site

turn off error reporting
create custom error messages

during site development

use highest level of error reporting
display notices, warnings, and errors

to change level of error reporting

reconfigure php.ini
PHP functions

When PHP encounters an error, it displays a message indicating the cause of the error, and if serious enough, terminates the execution of the script.

PHP has three basic types of errors.

ERRORS: fatal run-time errors, such as calling a function which does not exist. These cause immediate termination of a script.
WARNINGS: non-fatal run-time errors, such as trying to include( ) a file that does not exist.
NOTICES: less serious warnings which may result from a bug in your code, but may actually be intentional ( such as using an uninitialized variable knowing that it is automatically initialized to an empty string ).

PHP uses CONSTANTs to define the level of error reporting.

Each of these is defined by a named CONSTANT and an integer value.
CONSTANTs and numbers as defined in php.ini are:

E_ERROR	1	Fatal run-time errors that stop execution of the script
E_WARNING	2	Run-time warnings ( non-fatal errors )
E_PARSE	4	Compile-time parse errors
E_NOTICE	8	Notices ( things that may or may not be a problem )
E_CORE_ERROR	16	Fatal start-up errors
E_CORE_WARNING	32	Non-fatal start-up errors
E_COMPILE_ERROR	64	Fatal compile-time errors
E_COMPILE_WARNING	128	Non-fatal compile-time errors
E_USER_ERROR	256	User-generated error messages
E_USER_WARNING	512	User-generated warnings
E_USER_NOTICE	1024	User-generated notices
E_ALL		All errors, warnings, and notices

For the most part, you will not be concerned with the core or compile-time errors. By default, the current version of PHP sets error reporting to:

E_ALL & ~E_NOTICE

which means it reports on all errors except notices.

EG
// beginning text
echo “. . . begin text . . .”;

// include a non-existent file
include( ‘no_such_file.inc’ );

// print more text
echo “. . . end text . . . “;

generates a warning.

. . . begin text . . .
Warning: main(no_such_file.inc): failed to open stream: No such file or directory in
testError.php on line 26
. . . end text . . .

A fatal error, on the other hand:

// beginning text
echo “. . . begin text . . .”;

// call to a non-existent function
no_such_function( );

// this statement will not be executed
echo “. . . end text . . . “;

generates this fatal message:

. . . begin text . . .
Fatal error: Call to undefined function: no_such_function() in testError.php on line 29

For security reasons, it’s not a good idea to show users any error messages.

Some error messages, especially when used with a database, will reveal hidden aspects of your application, such as file paths, which could be used by someone trying to crack your site.

Displayed error messages on your site also look bad. Besides, they are often difficult to figure out.
In a production site, therefore, it is best to turn off error reporting, or create custom error messages.

You can change the level of error reporting in the php.ini file, or by using a PHP function.

On the other hand, when you are still in the development stages of a site, you may want to change the level of error reporting so that all errors, warnings, and notices display, making it easier to debug your site.
You can change the level of error reporting a couple of different ways.

php.ini

You can change the php.ini file, but this way permanently changes the default.

error_reporting = E_ALL

means that all errors, warning, and notices will be reported.

display_errors = Off

will turn off the PHP feature for displaying errors in the web page.

These are settings to change in php.ini

error_reporting( )

The function error_reporting( ), when passed one of the error CONSTANTs or numbers, will overwrite the default level for the duration of the script from which it is called.

Once you are finished with the development and are ready to place the script into production, you may want to turn off error reporting completely, so that a user will not see any errors, warning, or notices. This does not mean that errors will no longer occur – the user just won’t see them anymore.

// turn off all error reporting
error_reporting( 0 );

// beginning text
echo “. . . begin text . . .”;

// call to a nonexistent function
no_such_function( );

// this statement will not be executed
echo “. . . end text . . . “;

will print

. . . begin text . . .

While you are still in development, however, you may want error reporting turned on to its highest level:

// reports all errors, warning, notices
error_reporting( E_ALL );

// beginning text
echo “. . . begin text . . .”;

// call to an undeclared variable
echo $undeclared_var;

// this statement will not be executed
echo “. . . end text . . . “;

will print

. . . begin text . . .
Notice: Undefined variable: undeclared_var in testError.php on line 77
. . . end text . . .

will cause PHP to report on every error, warning, and notice that occurs.

While you are in the development stages of a script you may want to set the level this high so you can see every instance where there may be a problem.

You can customize the levels even more.

error_reporting( E_ALL & ~E_NOTICE );

which means that it reports all errors except notices.

shutting off error handlers with @

One other way to temporarily shut off error display is to use the at sign @ . Prefixing a function call with the @ operator suppresses error display

// beginning text
echo “. . . begin text . . .”;

// call to a nonexistent function
@no_such_function( );

// this statement will not be executed
echo “. . . end text . . . “;

will print

. . . begin text . . .

includes

One convenient way to apply the same error reporting level to an entire application is to set levels in an include file

error_reporting( E_ALL );

save as error_all.inc .

Then at the top of every file, at least during the development process, include the file:

include( ‘error_all.inc’ );

set_error_handler( )

When PHP handles an error, by default it identifies an error type, an error message, the file name, and the line number on which the error occurred.
You can also create your own functions to handle errors on your site using the set_error_handler( ) function.

When you create your own functions, PHP’s default behaviors are overwritten by your own function.
In other words, you can bypass PHP’s intrinsic functions for handling errors, and bypass them with your own.

The set_error_handler( ) function takes a single argument, the name of the function you have created to handle errors.
Your user-defined function must take at least 2 arguments:
error type
error message

and up to 3 additional arguments:
file name
line number
current PHP variables

EG
 // define custom error handler
set_error_handler( ‘customError’ );
 // create custom function to handle errors
function customError( $type, $msg ) {
 echo “<h1>Error!</h1>”;
 echo “Error code: $type ”;
 echo “Error msg: $msg ”;
 echo “Please contact your administrator.”;
}
// call to a nonexistent function
no_such_function( );

Error!
Error code: 2
Error msg: main(no_such_file.inc): failed to open stream: No such file or directory
Please contact your system administrator.

In this example, the normal error handling capabilities of PHP are overwritten by the call to set_error_handler( ), to which we have passed the name of our custom function.
This custom function, named customError( ) takes two arguments – the error type and the error message normally generated by PHP. We can then use those values anyway we want in our function.

If you would want to use the 3 optional arguments, your custom function definition would look like this:

function customError( $type, $msg, $file, $line, $vars ) {
// statements . . .
}

To customize the handling of the error even more, we can set our error message based on the error type:

function customError( $type, $msg ) {
 switch( $type ){
 case E_NOTICE:
 // do nothing
 break;
 case E_WARNING:
 echo “A non-fatal error occurred:
$msg ”;
 break;
 case E_ERROR:
 die( “A fatal error occurred: $msg ” );
 break;
 }
}

Pay special notice to case E_ERROR. You cannot over-write the default error handlers for E_ERROR or E_PARSE error types.
Even though you have a custom error handler set for E_ERROR, PHP will use its built-in handlers.

Notice the die( ) function ( really a language construct ).

The die( ) function is an alias for exit( ).

It terminates the execution of the script. It takes one argument, a string which is printed when die( ) is called.

When calling functions in your script, you might want to consider using die( ) in functions whose successful execution is essential for the running of the script, but the @ operator for functions which, if they fail, will not affect the functionality of the script as a whole.