Clickable stack traces with PHP Xdebug and Sublime Text (other editors/IDEs are available)

Have a look at this. Ugly, isn’t it? But so so useful.

If you don’t know what a stack trace is, this (above) is a stack trace; a list of functions and/or methods called leading up to the error which triggered the trace. The error itself is in the lovely orange section at the top, from this we can see the normal information about a PHP error and you might have seen similar messages printed on screen when you’ve made a programming boo-boo in the past. The table underneath in a delightful shade of grey, lists the function calls from the first point in your current PHP script to the function or method which called the function or method which contained the error.

A particularly great thing about this Xdebug enabled stack trace is that I can click on the file references and Sublime Text (my editor of choice) will open the relevant file at the relevant line so I can examine and edit the code there. Really handy.

There are a couple of tricks involved in having this information display in your development environment (do not install this on a production server, as users don’t want to see this kind of explosion of your website’s programming guts all over their screen). First you’ll need Xdebug, which gives you the useful stack trace, and then you’ll need to configure Xdebug to provide the correct links and ensure that your editor is setup to understand those links. I can help you with some of these things.

Setting up Xdebug

I currently use MacPorts (Homebrew users, form a orderly line to tell why I shouldn’t be using Macports… but until I upgrade this machine I’m sticking with it), and installing Xdebug is a simple matter of running the following from the terminal:

sudo port install php5-xdebug

Homebrew users (see, I’ve nothing against you…) I think you can use Jose Diaz-Gonsalez’ formula on Github.

Configuring Xdebug

Locate your php.ini file, and check for an existing section of settings with the xdebug. prefix. You want to add or amend the xdebug.file_link_format setting to specify (for Sublime Text and Textmate) a link with the txmt:// protocol. Here’s what I have for that setting:

xdebug.file_link_format="txmt://open/?line=%l&url=file://%f"

TextMate implements the txmt:// protocol with no further effort, so TextMate users can head for the kettle now.

Sublime Text can piggy back on the txmt:// protocol using Scott Walden’s subl-handler app which you can download from the Github project. I had to remove Textmate and Text Wrangler from my system, as they both seemed to “get at” the file before Sublime Text was passed it; no great loss for me, as I’ve switched solely to Sublime Text.

Bonus

I listened to Derick Rethans, the creator of Xdebug, give an overview of it’s capabilities the other year and there’s a couple of things I took from that which form part of my daily development bag-o-tricks:

Xdebug enhances and nicely styles the output from var_dump, which makes it a lot easier to see what’s going on in any variables you, errr, dump. Really handy, and ‘Just Works’ when you’ve got Xdebug installed.

The xdebug.scream PHP INI setting is really handy. sometimes you come across code which uses the PHP @ error suppression operator. This operator is a bit tricky, on the one hand it vastly simplifies a number of situations where you really aren’t sure if you’re going to get an error, and on the other hand if you end up executing a significant quantity (or some would say, any) code behind the error suppression and you get… a fatal error (say, because you’re using a function which doesn’t exist), it can be very difficult to work out what’s failing and why, because the screen just goes white and PHP collapses down dead. The xdebug.scream setting removes the error suppression so you get to see all the notices, warnings and fatals it would otherwise have hidden… really handy for debugging.

Update: As Sam de Freyssinet prompts me to point out, if you’re using the @ error suppression then 99.99% of the time there’s a better solution you could come up with, so it’s worth considering alternative approaches to your problem.

So there you go… Xdebug clickable stack traces and a few bonus features too. There’s other things you can do with Xdebug, including stepping through your code with breakpoints and variable examination… but that’s for another day and another post.

Update: I’ve also written an article about getting clickable stack traces running with Netbeans.