Saturday, January 30, 2016

Creating live links in Whoops (Laravel 5.1 edition)

Whoops is "an error handler framework for PHP. Out-of-the-box, it provides a pretty error interface that helps you debug your web projects, but at heart it's a simple yet powerful stacked error handling system." I was introduced to it in Laravel 4, but then it was removed in Laravel 5. Matt Stauffer and then Ryan Winchester provided instructions on bringing Whoops back into Laravel 5.x and it's much nicer than the standard Laravel error message.

Out-of-the-box, it also provides 'live' links into your code, directly to the file and line on which the error occurred, and all the way through the stack trace. Pick a point in the stack, click on the file link, and if you've set the editor properly in the Whoops handler, you're instantly in the correct spot in your code!

That is unless the error occurs on a server, and that server has a different base path than the machine where your code resides. A server running on a Vagrant box for instance. Like many other things, the server path has to be mapped to a local path. In the Whoops error handler, it needs to map to the correct local-to-your-editor file location so Whoops can build the correct links.

Here's the way to do that:

First follow Ryan's excellent instructions for getting Whoops running in Laravel 5.1. Then modify this area of his code:

To this:

And add a 'vagrant home' variable to .env:

In the new callback in handler.php:
  • line 12 adds a $translations array that rewrites the source file location from 'remote' to 'local' directories
  • line 15 performs the 'translations' and urlencodes the resulting location
  • line 19 sets the editor. This doesn't have to be Phpstorm by any means. Whoops PrettyPageHandler contains a list of editor links. The path for Sublime would be "subl://open?url=file://$file&line=$line" or MacVim: "mvim://open/?url=file://$file&line=$line"

Also fix the CSS

I wasn't entirely happy with some of the new Whoops 2.0 css, so I overwrote some of it in an alternate whoops.base.css file which has to be registered with Whoops, so:
  • line 24 adds another local-to-the-app resource path
  • line 25 adds the custom css
Which is just this:

The original Whoops 2.0 css lives in {doc_root}/vendor/filp/whoops/src/Whoops/Resources/css/whoops.base.css


Kitepro said...

Great article.

What about sublime editor?

And where is the whoops css? Which file should I edit to overwrite the css?

Jon Phipps said...

The path for Sublime would be "subl://open?url=file://$file&line=$line" or MacVim: "mvim://open/?url=file://$file&line=$line"

The original Whoops 2.0 css lives in {doc_root}/vendor/filp/whoops/src/Whoops/Resources/css/whoops.base.css

You can copy the entire file if you want and put it in any path in your project, as long as you tell the handler what that path is (line 24). Register your custom CSS with the handler (line 25) and it will be loaded after the whoops.base.css, rewriting any styles you modify.