Custom Error Handling and Debugging

In our development environment we want to see all error details in the browser, but on the live site we don't want to show any error messages. Instead we want them to see a 'friendly' message, and we want the ugly details of the error to be emailed to us (so that we are aware that an error occured on the live site). In this step, we'll set up custom error handling.

1. Update the config file (config.inc.php) to look like this.

   We've added some new constants to our config file, DEBUG_MODE and ADMIN_EMAIL

   • Set ADMIN_EMAIL to be your email address.
   • Set DEBUG_MODE to true for localhost and false for the live site settings.

   The reason for DEBUG_MODE is that we might possibly want to display error messages on the live site under certain circumstances. For example, if there is an error occurring on the live site, but not on dev, then we can simply change DEBUG_MODE to true for the live site settings. Notice that we've added an IF statement that checks to see if we are in debug mode, if so we want PHP to display all error messages. Make sure to set ADMIN_EMAIL to your own email address.

2. Now we are going to add a few functions to the config file. Functions defined in the config file will be available to all web pages.

   • First add sendEmail() which will be a 'wrapper' function for the built-in mail() function in PHP.
     This is what the function should look like.
     Put the function at the bottom of the config file, note that I have put a comment between the functions and the rest of the code above. We could just use the mail() function when we want to send an email from a page, but instead will call sendEmail(). This gives us the flexibilty to update the sendEmail() function in the future without having to update all pages that may have otherwised used mail();
     
     
   • Now we'll add our own custom error handler function, and then we'll set it to be the function that PHP calls when it encounters an error.
     Here is the code. There is another function named getAllSuperGlobals() included in the code sample. It simply builds a string of all data stored in the super global arrays. This information can come in handy when you are trying to make sense of an error, so we'll include it in our error handling.
     Note that if we are in debug mode, an error is displayed in the browser, otherwise the error message is sent to the ADMIN_EMAIL address and then we use the header() function to redirect the user to a page that displays a 'friendly' error message (we'll add this page in the next step). You can read about the header() function in chapter 10 of the book.
     
     
   • Finally, add this line of code to the top of the config file. It uses the set_error_handler() function tell PHP to use our own error handling function (customErrorHandler) instead of the default one.

3. Adding an Error Page

   Create a file inside the 'my-new-site' folder named error.php. You can copy the contents of the site home page into it and then make the following changes:

   • Update the page specific variables ($pageTitle, $pageDescription, $sideBar).
   • Update the content within the main tag so that it displays a friendy message, make sure that you mention that you have been notified of the error and will fix it asap. For example: We seem to have encountered and error! We humbly apologize, and want you to know that we have been informed of the error and will work diligently to correct it as soon as possible.

4. Test It!

   Go ahead and generate an error in the code of the site's home page (echo a variable that doesn't exist). You should see your custom error handling function.

   At this point you should test this code on your live server, but we may not have set it up just yet.

   SIDE NOTE: I did not add a SERVER error header to the error page. Normally whan an error occurs on the web server, we should technically return a HTTP status code of 500. We'll talk more about http headers later in the course.