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:

• 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 “<p>. . . begin text . . .</p>”;     

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

       //  print more text
       echo “<p>. . . end text . . . </p>“;

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 “<p>. . . begin text . . .</p>”;     

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

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

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 “<p>. . . begin text . . .</p>”;     

//  call to a nonexistent function
       no_such_function( );

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

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 “<p>. . . begin text . . .</p>”;     

//  call to an undeclared variable
       echo $undeclared_var;

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

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 “<p>. . . begin text . . .</p>”;     

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

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

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 “<p>Error code: $type <br />”;
       echo “Error msg: $msg </p>”;
       echo “<p>Please contact your administrator.</p>”;
  }
//  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 “<p>A non-fatal error occurred:
$msg </p>”;
                  break;
             case E_ERROR:
                  die(  “<p>A fatal error occurred: $msg </p>” );
                  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.