Series Contents

Part 6. Debugging Made Easy.


Whoops! We had an error and now we have to look at that ugly, fairly uninformative error page. How many times has that happened to you? Too many? Yeah, same here. I really hate those uninformative “Hey, something broke but we’re not going to tell you what” errors.

Now I will say, the guys at Slim have made some improvements over the default PHP error page. We now get a message, file/line, and a simple stack dump. This is something I really appreciate as it at least gives you a place to start looking. But I would still like to see more.

Thanks to Zeuxis Lo we now have a slim port of the very cool Whoops debug library. Whoops takes that basic stack trace and actually shows you a view into each file/line. Giving you a code view for all frames in a stack trace with line highlights. It also gives you all of your environment variables and their details. This looks much better than the default PHP or Slim error pages.

alt text


We’ll be adding this as a middleware.

What’s middleware you ask? Well, by definition middleware is…

Code that changes the default application behavior and can be added at different stages during the request/response cycle.

In other words, you can hook into your application before and after specific points during the execution; Allowing us to modifying either the Request or the Response. This can be very useful for automatically handling things like authentication checks, logging, or providing CSRF protection. More information on how Slim handles middleware and how you can even write your own can be found in the Slim documentation,.

In our case we will be hooking into Slim’s error handler, catching Errors and Exceptions, and giving a nicely formatted view to you the developer. Lets get started.

Installation and setup.

Lets start by installing this middleware with Composer.

There are two configurations settings that we need to add to our settings.php file. One tells Whoops! whether to show errors the other is which editor to use to open a file from the stack trace. Available built-in editors are: sublime, phpstorm, emacs, textmate, or macvim. I usually put these right under the setting for ‘displayErrorDetails’, just to keep things organized.

You may have noticed that ‘debug’ duplicates the ‘displayErrorDetails’ settings. Although I usually abhor duplication in my code this instance is a nessesity. While parts of the Slim core use ‘displayErrorDetails’ setting, the Whoops! package looks for the ‘debug’ setting. We’ll have to deal with this one line for now.

The final step will be to add the Whoops library as middleware in our application. Lets add the following lines to your middleware.php file and then I’ll explain what is going on.

The first line gets the container from the application as we have done before. The next thing we will do is check to see if we are displaying errors for this environment. This setting is held in our containers settings as ‘displayErrorDetails’. This conditional check is very important as we would not want to show these details to the end user in, say, a production environment. So, if ‘displayErrorDetails’ is set to true, such as when we are in a development environment, then we will add the middleware wrapper to the application container. This will make sure that it is called whenever there is an error.

See it in action.

To view an example of a Whoops error dump lets add a new route that throws an error on purpose.

Open your routes.php file and add a new route before the existing default one.
Why before? Because the default route uses an optional named placeholder that accepts anything after the initial /. If we put our new route after this it will never be reached because the default route acts like a catchall.

Here is our new error route definition.

Now lets add a new callback in our default controller for this route to hit. Open DefaultController.php and create a new method called ‘throwException’ with the following code.

Here we are doing nothing more than logging the fact that we are here to the message log, and then throwing a PHP Exception for Whoops to catch. Browsing to will now give us a Whoops error page with lots of useful debug information. This includes not only the stack dump, but a highlighted view of the code where the exception was raised along with any environment details.

So now, not only do we now know how to add pretty error handling, but we have also learned how to install a simple middleware. Most middleware is fairly simple to implement. Good middleware maintainers will most certainly have installation documentation with any extra options explained.

Until next time, happy debugging.


See the final code for this article on Github. 006 Debugging Made Easy


Slim-OO Part 7. Flash messaging