Debugging PHP with Sublime Text 2

$ sudo add-apt-repository ppa:webupd8team/sublime-text-2;
$ sudo apt-get update;
$ sudo apt-get install sublime-text

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:

lrwxrwxrwx 1 root root 25 Nov 13 11:36 10-pdo.ini -> ../mods-available/pdo.ini
lrwxrwxrwx 1 root root 26 Dec 11 15:29 20-curl.ini -> ../mods-available/curl.ini
lrwxrwxrwx 1 root root 24 Nov 19 02:25 20-gd.ini -> ../mods-available/gd.ini
lrwxrwxrwx 1 root root 28 Nov 13 15:20 20-mysqli.ini -> ../mods-available/mysqli.ini
lrwxrwxrwx 1 root root 27 Nov 13 15:20 20-mysql.ini -> ../mods-available/mysql.ini
lrwxrwxrwx 1 root root 31 Nov 13 15:20 20-pdo_mysql.ini -> ../mods-available/pdo_mysql.ini
lrwxrwxrwx 1 root root 28 Dec 26 17:46 20-xdebug.ini -> ../mods-available/xdebug.ini

On my fairly new Debian based distribution, the correct way to remove Xdebug from the /etc/php5/conf.d folder is:

$ sudo php5dismod xdebug

But if you don’t have the php5enmod / php5dismod commands, you may just as well just delete the symlink using rm:

$ rm /etc/php5/conf.d/xdebug.ini

With Xdebug out of the global config, you want to add it to the config for cli. So in the file /etc/php5/cli/php.ini, you add at the very end:

[xdebug]
zend_extension=/usr/lib/php5/20100525/xdebug.so
xdebug.remote_enable=On
xdebug.remote_host="localhost"
xdebug.remote_port=9001
xdebug.remote_handler="dbgp"

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:

import urllib2,os; pf='Package Control.sublime-package'; ipp=sublime.installed_packages_path(); os.makedirs(ipp) if not os.path.exists(ipp) else None; urllib2.install_opener(urllib2.build_opener(urllib2.ProxyHandler())); open(os.path.join(ipp,pf),'wb').write(urllib2.urlopen('http://sublime.wbond.net/'+pf.replace(' ','%20')).read()); print 'Please restart Sublime Text to finish installation'

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:

1. Download Python 2.6 from the Ubuntu archives
2. Extract Python 2.6 under the Sublime Text lib folder
3. Clean up

Like so (if you’re on a 64 bit machine):

$ wget http://security.ubuntu.com/ubuntu/pool/main/p/python2.6/python2.6_2.6.5-1ubuntu6.1_amd64.deb
$ dpkg-deb -x python2.6_2.6.5-1ubuntu6.1_amd64.deb python2.6_2.6.5
$ sudo cp -r python2.6_2.6.5/usr/lib/python2.6 /usr/lib/sublime-text-2/lib/
$ rm -rf python2.6_2.6.5
$ rm -rf python2.6_2.6.5-1ubuntu6.1_amd64.deb

And like this if you’re on a 32 bit machine, it should work like this, however I never tried it:

$ wget http://security.ubuntu.com/ubuntu/pool/main/p/python2.6/python2.6_2.6.5-1ubuntu6.1_i386.deb
$ dpkg-deb -x python2.6_2.6.5-1ubuntu6.1_i386.deb python2.6_2.6.5
$ sudo cp -r python2.6_2.6.5/usr/lib/python2.6 /usr/lib/sublime-text-2/lib/
$ rm -rf python2.6_2.6.5
$ rm -rf python2.6_2.6.5-1ubuntu6.1_i386.deb

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):

Test time

All the pieces are in place, let’s try to do a simple debug session.

1. Create a script to debug

<?php

$foo = array('Abba' => 'Sweden', 'Beatles' => 'England', 'Beach Boys' => 'USA');

foreach($foo as $k => $v)
{
echo "Band {$k} \t Country {$v}\n";
}

2. Launch a PHP webserver. In a terminal window, navigate to the folder where you saved the script above and type:

$ php -S localhost:8000
PHP 5.4.6-1ubuntu1.1 Development Server started at Wed Dec 26 23:44:16 2012
Listening on http://localhost:8000
Document root is /home/erik/src
Press Ctrl-C to quit.

3. In Sublime Text, set a breakpoint on a suitable line (note: can’t be a blank line) by putting the cursor on that line and hit Ctrl+F8, you should see a round marker in the left margin.

4. In Sublime Text, enter debug mode by hitting Shift+F8 and select ‘Start Debugging’ from the menu that appears.

5. In Chrome, surf to http://localhost:8000/test.php. Click on the gray ‘bug’ icon in the address field to make it grren. Then refresh the page again

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.

To finish of, go to https://github.com/Kindari/SublimeXdebug to read more about the tool and then, enjoy.

/E