Menu

Debugging PHP with Sublime Text 2

In my early days of developing, I was heavily using Microsoft Visual Studio almost exclusively and say what you want about developing in the Microsoft ecosystem, but debugging Just Worked. In the Open source world of various iteration of LAMP stack, debugging is more of a challenge and honestly, just as many other developers working with PHP, I quite often just decide to live without step-by-step debugging.

However, on my latest development machine, I did make the effort and put all the pieces together and as much as I want to share, this blog post mostly serves as a memory backup knowledge for myself.

Part list

A little bit about my environment:

My development machine is a laptop with Ubuntu 12.10 on it. Most of these instructions should work just fine on most other Linux distros as well.

I use Sublime Text 2 as my primary code editor. I like it a lot and I also selected it partly it can do debugging. (and yes, I did shell out the money for a license, suggest you do the same if you use it daily)

I have Apache2 installed on this development machine, but I have selected not to to enable Xdebug in apache2. Instead, I use PHP built in webserver (introduced in php 5.4)when I want to debug in the code.

INSTALLING XDEBUG

Getting it onto the machine should be very straight forward:

$ sudo apt-get install php5-xdebug

So, but I had this minor itch that I wanted to scratch. Even if this is my development machine, I’d like to keep Xdebug out of the Apache2 installation, instead, I want to do my debugging via the built in PHP web server, to me that makes more sense.

After Xdebug is installed, it also updates php5 configuration on the box so that it’s globally available, so regardless if you run php from Apache2 and from command line. This is achieved by a little symlink magic. The content of my /etc/php5/conf.d directory:

So, now Xdebug is available only when php is run via the command line and not via Apache2.

Installing Sublime Text package control

By far the easiest way to get various Sublime Text packages installed is to use the package manager Package Control. It’s a full-featured package manager that helps discovering, installing, updating and removing packages for Sublime Text 2. It features an automatic upgrader and supports GitHub, BitBucket and a full channel/repository system.

Installation is extremely easy via the Sublime Text console. In Sublime, you either select View -> Show Console or via the shortcut Ctrl+’. In the console, paste the following command:

Once you restart Sublime Text 2, you should have ‘Package Control’ in the Preferences menu. Read more about installing and trouble shooting Package Control here.

Installing Kindaris Sublime Xdebug

Finally, almost the last piece of software to install. Kindari’s Sublime Xdebug client. In Sublime Text 2 go to the preference menu and select Package Control => Install package. You should see something like this:

Now, select Install Package and type xdebug. The search function should more or less immediately give you Xdebug – Xdebug Interface for Sublime… as an option. Just select it and let the installation begin. There. Done. Almost.

INSTALLING Python 2.6 packages

Xdebug Interface for Sublime depends on a package from Python 2.6, so to get it to work on your machine, chances are that you need to install Python 2.6. On later releases of Ubuntu, it’s not possible to install Python 2.6 via the repos. But there is a fairly easy way to get the package we miss:

Last piece – Xdeubg Helper for Chrome

With the above pieces in place, Xdebug is really good to go. However, to get Xdebug to work, you need a way to trigger it and the most common (or at least easiest) way to do it for web development is via Xdebug remote debugging. To trigger the debugger, get your web browser to send an additional parameter XDEBUG_SESSION with a value that matches a predefined string in your IDE. You can send the additional parameter as a GET query parameter, but that will quicky get complicated and / or cumbersome depending on your URL structure. With the XDEBUG Helper extension for Chrome, you force Chrome to send that additional parameter in the background whenever you need it to.

Go to the Chrome Web Store and search XDEBUG Helper in the Extensions section and then add it to chrome. Then go to the Options screen for the extension and add sublime.xdebug as the IDE key. Optionally, you may also want to white list your own machine in the Domain filter section. By doing that, the XDebug helper icon will only show up when you’re surfing on a page that you can actually debug on. Below is my options screen (click to enlarge):

6. Hey presto!!!! In Sublime, you should now see a small triangle on the first line with a break point that indicates that it’s the next line to be executed.

You are now debugging your code inside Sublime Text 2.

Shortcut keys

Shift+f8: Open XDebug quick panel

f8: Open XDebug control quick panel when debugger is connected

Ctrl+f8: Toggle breakpoint

Ctrl+Shift+f5: Run to next breakpoint

Ctrl+Shift+f6: Step over

Ctrl+Shift+f7: Step into

Ctrl+Shift+f8: Step out

Trouble shooting

I’ve only had one real problem setting this up on my machine. When I first tried this, the sublime xdebub panels ‘Context’ and ‘Stack’ would stay blank and the debugger refused to connect to the IDE. The problems turned out to be that I missed the Python 2.6 packages mention above. So make sure not to skip the section ‘Installing Python 2.6 packages’ above.

Did u already installed Xdebug Helper for Chrome as per the instruction above there? mine is working after I did that. Once you install it, enable the debug icon that looks like a bug just on the far right side of the URL bar, once it turned green, then refresh your page, the debugger in your Sublime will run at once. Cheers