Errors & Debugging

All of Garden's custom error handling is accomplished with PHP's set_error_handler function, which allows you to call your own function whenever an error occurs. There are a few shortcomings where your custom function will not get called. To quote the PHP manual:

The following error types cannot be handled with a user defined function: E_ERROR, E_PARSE, E_CORE_ERROR, E_CORE_WARNING, E_COMPILE_ERROR, E_COMPILE_WARNING, and most of E_STRICT raised in the file where set_error_handler() is called.

If errors occur before the script is executed (e.g. on file uploads) the custom error handler cannot be called since it is not registered at that time.

Luckily, 99% of these "unhandled" errors are extremely easy to debug. Since Garden does most of it's complex processing before the page is rendered, these unhandled errors will typically look like this:

This example is a parser error, and obviously occurred on line 19 of that particular file because a class that was being instantiated had not yet been declared. An easy fix.

But, as you can imagine, errors can be much more difficult to debug than that, and so enters Garden's error page:

This error page is completely contained within the error.master view. If for some reason Garden fails to find the error master view, it's error function has a simpler version of this page explaining the error.

What you get

Fatal Error in PHP.ErrorHandler(); tells you what object & method threw the error. In this example, it was a PHP error (ie. totally unexpected by the application). If it is a custom Garden error, you might see something along the lines of: Fatal error in ProfileController.BuildSideMenu();.

Next you get the actual error message. In this case: Undefined property: ProfileController::$DoesntExist

Everything after the error message provides information about that error message, starting with:

• Where the error occurred: This example first tells you in what file the error occurred, followed by an excerpt from the file with the actual error line highlighted.
• Backtrace: Next you get a backtrace of what files & functions/methods were called which led to the error. The backtrace can be invaluable in figuring out what actually led to the error being thrown.
• Queries: Next you have a summary of all database queries that were run before the error was encountered.
• Variables in local scope: Finally, if there are any variables in local scope at the time of the error, their names & values will be written out. In this example, there are no variables in local scope, so there are none written.
• Additional Information: If dealing with a remote bug, it is always incredibly helpful to get additional information about the system on which the application is running. So, the additional information section contains information about:
  • What version of Garden is running.
  • What version of PHP is running.
  • What operating system the server is running.
  • What referrer led to the page where the error was thrown.
  • What user-agent was being used when the error was encountered.
  • The request route that led to the error.

Using the Error Page

I found that there was a small bit of a learning curve with using this error page. I was just used to having to deduce what the problem might be and following my gut instinct as I did with most of Vanilla 1. However, after a few days with all of this information available, I found that bugs were getting resolved faster than ever before. Now I am at the point where a quick glance at the error page can tell me exactly what the problem is so I can be moving ahead in a matter of moments. I know that it will be invaluable to both application and plugin developers.

Post Launch Errors

Of course, we don't want end users to have to deal with an error screen like this. With that in mind, Garden has a "Debug Mode" switch that, unless turned on, tells Garden to use a *different* master view for errors. The other master view, which can be customized further using themes, simply states that an error was encountered and that the user should report the problem to an administrator. Error mode will be turned off by default in the release version of Garden.