Debugging your phpunit test cases in CodeIgniter

I don’t know why it feels ironic, but it does. Sometimes I need to debug my phpunit test cases and it wasn’t very very self explanatory to understand how to set it up . The solution however, is quite easy.

I’ve previously written about how to enable the php debugger xdebug from a command line script. The end result from reading that article should be that you have a php5d command on your system that will trigger xdebug to hook into your IDE (mine is Sublime Text 2, yours may differ). For the rest of this article, I’m going to assume you have the php5d command available.

Next step is to prepare your test classes for execution via a php command rather than via the phpunit framework (don’t worry, it will be included). The solution to this was found at Stack Overflow (naturally, read it, it’s good), but I  found out that two simplifications can be made when used in CodeIgniter with CI_Unit.

The foundation of the StackOveflow trick is to make sure that a couple of PHPUnit classes are loaded, either via explicit statements as the sample suggests, or via the PHPUnit/Autoload functionality. Turns out that when bootstraping PHPUnit via CI_Unit, it already brings in PHPUnit/Autoload.php. That makes it one less requre_once statement to forget about.

The second simplification is to minimize the room for copy / paste related errors. As long as you are a bit obsessive with class names and make sure that your file name is always classname.php (so class FooTest is implemented in the file FooTest.php), then you can avoid typing the class name in one additional place. That’s exactly what I need to do myself to avoid hard to catch errors.

My test cases are now modeled after this template:

<?php
/**
* Tests for the Foo class
*/
require_once('../application/third_party/CIUnit/bootstrap_phpunit.php');

class FooClassTest extends CIUnit_TestCase
{
static function main() 
{
  $suite = new PHPUnit_Framework_TestSuite( __CLASS__);
  PHPUnit_TextUI_TestRunner::run( $suite);
}

public function setUp()
{

}

public function testSomething()
{
  $this->assertTrue(FALSE);
}
}

if (!defined('PHPUnit_MAIN_METHOD')) {
  $class = str_replace('.php','', basename(__FILE__));
  $class::main();
}

And to actually debug it (assuming that the above test class is stored in tests/lib and is naturally named FooClassTest.php), I type:

$ cd tests
$ php5d libs/FooClassTest.php

And to run it under PHPUnit, it’s works just as you’re used to already.

/E

Debug PHP-cli scripts with Xdebug and Sublime Text 2

In my previous post, I explained how I’ve set up debugging PHP scripts with Xdebug and Sublime Text  2 in a web based environment. In this part, I’ll outline how I debug PHP command line scripts.

If you want to follow this guide, make sure you have everything setup as explained in the previous post.

Triggering Xdebug

When using Xdebug from a web browser, I use the Chrome extension Xdebug Helper to send a valiid XDEBUG_CONFIG parameter string to the PHP process. The magic part is to set the idekey parameter to sublime.xdebug (sent via the cookie). To do the  same thing when running a script from the command line, the magic trick is to use the environment variables. This is explained in the Xdebug manual, like this:

export XDEBUG_CONFIG="idekey=session_name"
php myscript.php

Oh, how cumbersome to type. Let’s do that in a script instead. Create a file php5d like this:

#!/bin/sh
export XDEBUG_CONFIG="idekey=sublime.xdebug"
php5 $@

Make the file executable:

chmod +x php5d

Then give it a try, let’s debug the test script we created in the previous post, test.php:

  1. Open test.php in Sublime Text 2
  2. Start a debugging session by hitting Shift+F8
  3. Set a breakpoint on a suitable line (must be a non-blank line)
  4. Run the script: php5d test.php

You should see something like this:

Debugging_sublime

One last thing

With the php5d script in place, it’s easy and straight forward to debug command line scripts without doing too much damage on the normal environment. The last thing I did in my environment was to put the script in my /home/erik/bin folder to make it callable from everywhere on my machine:

Make sure I’ve got a central place for your personal scripts. At the end of your ~/.bashrc, make sure you have a line like this (you may already have something similar in place, I’m using subfolder bin, you may use something else):

## Additional personal scripts etc.
PATH=$PATH:"~/bin"

Then, copy the php5d script to the intended folder:

mv php5d ~/bin

And reload .bashrc (or just start a new terminal window)

. .bashrc

There you go, a globally available php5d command that triggers debugging in Sublime Text 2 for whatever PHP script you launch. Enjoy

/E

 

 

 

 

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