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)
  • In Sublime Text 2, I’m using Kindaris Sublime Xdebug client
  • 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.
  • I’m using Xdebug as the actual debugger.
  • To trigger debugging, I use the chrome extension Xdebug helper

Getting started

Here we go

Installing Sublime Text 2

(read more about Sublime Text 2)

Depending on your precise environment, how and where you install Sublime Text may vary. On Ubuntu 12.10, the by far easiest way is to get it via the http://www.webupd8.org/ like this:

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

PackageControl_1

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

Screenshot from 2012-12-26 23:16:25

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

Xdebug-for-chrome

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.

Debugging_sublime

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

 

 

 

 

 

PHP CodeSniffer and CodeIgniter

I recently found out that Thomas Ernest have created a CodeIgniter standard for CodeSniffer. He mentioned on the CI formus that it’s not perfect and does spit out a few warnings and errors for things that are really OK in the CI style guide. False positives.

This is the slightly modified welcome.php controller file I wanted to scan. According to my understanding of the CodeIgniter style guide, it should pass with flying colors:

<?php if ( ! defined('BASEPATH')) exit('No direct script access allowed');
/**
* File: welcome.php
* 
* PHP version 5
*
* @category Frontend
* @package  Citest
* @author   Erik Torsner <erik@torgesta.com>
* @license  torgesta.com http://www.torgesta.com/  
* @link     http://www.torgesta.com/  
*/

/**
 * Class Welcome
 *
 * @category Frontend
 * @package  Citest
 * @author   Erik Torsner <erik@torgesta.com>
 * @license  torgesta.com http://www.torgesta.com/
 * @link     http://www.torgesta.com/  
 **/
class Welcome extends CI_Controller {
	/**
	 * Index Page for this controller.
	 *
	 * Maps to the following URL
	 * 		http://example.com/index.php/welcome
	 *	- or -  
	 * 		http://example.com/index.php/welcome/index
	 *	- or -
	 * Since this controller is set as the default controller in 
	 * config/routes.php, it's displayed at http://example.com/
	 *
	 * So any other public methods not prefixed with an underscore will
	 * map to /index.php/welcome/<method_name>
	 *
	 * @see http://codeigniter.com/user_guide/general/urls.html
	 * @return void
	 */
	public function index()
	{
		$this->load->view('welcome_message');
	}
}

/* End of file welcome.php */
/* Location: ./controllers/welcome.php */

See? File doc comment, class doc comment, function doc comment, no PHP end tag but the two standard comments instead. Beautiful. But scanning with CodeSniffer, I’d get something like this:

$ phpcs --standard=CodeIgniter welcome.php 

FILE: /home/foo/src/citest/application/controllers/welcome.php
--------------------------------------------------------------------------------
FOUND 3 ERROR(S) AFFECTING 3 LINE(S)
--------------------------------------------------------------------------------
  1 | ERROR | Missing file doc comment
 47 | ERROR | Multi lines comments are not allowed; use "// Comment" DocBlock
    |       | comments instead
--------------------------------------------------------------------------------

Time: 0 seconds, Memory: 3.25Mb

First problem, CodeSniffer doesn’t see the file doc comment at all. Turns out the CodeSniffer looks for the first non white space token after the PHP open tag. If it’s a valid file doc comment, all is good. In CodeIgniter, the standard behavior is to add a check for “BASEPATH” right at the top and it gets in the way of finding the existing file doc comment.

Second problem. CodeIgniter style guide first say that all code comments should be one line comments. A few examples:

<?php

// One line comment using '//'. Fine with CodeIgniter 
$foo = "bar";

/*One line comment using '/*', not OK */
$fuu = "bar";

// Multi line comments, you should still use '//'
// This is the next comment line
$fuubar = NULL:

/* Multi line comments, this way is not OK
*This is the next comment line */
$fuubar = 42:

// But wait! at the end of the file. CI expects this:
// Two single line comments using '/* ... */. 
/* End of file welcome.php */
/* Location: ./controllers/welcome.php */

This is simply not consistent. To get clean scans using CodeSniffer, you have two options. Rewrite all end-of-file comments to use ‘//’ rather than ‘/*’ or fix CodeSniffer. Even if consistency is a good thing, this is a very well established style in CodeIgniter so I was inclined to fix CodeSniffer rather than fight.

The CodeSniffer standard is installed (on Ubuntu) in

/usr/share/php/PHP/CodeSniffer/Standards/CodeIgniter

 

To fix the comments, I made the following change to

/usr/share/php/PHP/CodeSniffer/Standards/CodeIgniter/Sniffs/Commenting/InlineCommentSniff.php

 

    private function _checkCommentStyle(PHP_CodeSniffer_File $phpcsFile, $stackPtr)
    {
        $tokens = $phpcsFile->getTokens();

        $cmt = $tokens[$stackPtr]['content'];
        if($this->beginsWith($cmt, '/* End of file')) return TRUE;
        if($this->beginsWith($cmt, '/* Location:')) return TRUE;
        ...
        ...

That it, to explicitly allow the two CodeIgniter specific comments. The second change was bigger. The CodeIgniter standard for CodeSniffer reuses PEAR’s check for file doc comments. Rather than modifying what is a built in CodeSniffer standard, I copied the correct file to the CodeIgniter standard and made modifications there. So I created the file

/usr/share/php/PHP/CodeSniffer/Standards/CodeIgniter/Sniffs/Commenting/FileCommentsSniff.php

 

as a copy of the corresponding file from the PEAR standard. Function process was modified:

    public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr)
    {
        $this->currentFile = $phpcsFile;

        // We are only interested if this is the first open tag.
        if ($stackPtr !== 0) {
            if ($phpcsFile->findPrevious(T_OPEN_TAG, ($stackPtr - 1)) !== false) {
                return;
            }
        }

        $tokens = $phpcsFile->getTokens();

        // Allow CodeIgniter std "if ( ! defined('BASEPATH')).... on the first line
        // keep iterating until we find a token on line 2...
        $startLine = $tokens[$stackPtr]['line'];
        $lastToken = $stackPtr;
        while($tokens[$lastToken+1]['line'] == $startLine) {
          $lastToken++;
        }

So, a simple loop that simply ignores whatever tokens that  is on the same line as the PHP open tag. Simple and it works. The last change I made was in

/usr/share/php/PHP/CodeSniffer/Standards/CodeIgniter/ruleset.xml

 

where the rule that refers to the FileCommentSniff file is modified so that it looks at the local copy rather than the one from the PEAR standard. Just change the line:

<rule ref="PEAR.Commenting.FileComment">

Into

<rule ref="CodeIgniter.Commenting.FileComment">

That’s it. A new test scan reveals that the perfectly decent looking welcome.php doesn’t generate any further errors:

$ phpcs --standard=CodeIgniter welcome.php 
Time: 0 seconds, Memory: 3.25Mb

Now, go to github and get the repo.