Debugging PHP commandline applications with IntelliJ

Usually I don’t need much debugging with PHP. But recently I tried to create a TestCase and there was an issue which I simply couldn’t find. While I had xdebug in place for my Apache HTTPD delivered applications, I had not anything ready for debugging CLI. Luckily it turned out to be pretty easy, thanks to xdebug, Mac Ports and the fantastic IntelliJ IDE.

Most of us already know that the PHP version on command line might not match the version used by PHP. In my case, OS X delivered a PHP binary to /usr/bin/php. It was not the one I wanted, I wanted to go with the one I installed with Mac Ports. Actually I could not edit the php.ini file which was used, not even with superuser rights. Therefore:

rm /usr/bin/php
rm /usr/bin/php-config

This will delete the OSX pre-installed binaries (at least under 10.6.x).

For the sake of completeness, here is how you can install PHP and xdebug with Mac Ports:

$> port install php53
$> port install php53-xdebug

Your new PHP binaries should be available in /opt/local/bin. It is the default directory where Mac Port puts binaries and should be already available on your path.

If everything is alright, you should see something like that on your screen when asking for the version:

$ php --version
PHP 5.3.9 (cli) (built: Feb  1 2012 16:51:36) 
Copyright (c) 1997-2012 The PHP Group
Zend Engine v2.3.0, Copyright (c) 1998-2012 Zend Technologies
    with Xdebug v2.1.1, Copyright (c) 2002-2011, by Derick Rethans

If you miss the xdebug information, please check if this file has been created: /opt/local/var/db/php5/xdebug.ini.

It should look like that:

zend_extension=/opt/local/lib/php/extensions/no-debug-non-zts-20090626/xdebug.so

xdebug.remote_enable=on
xdebug.remote_handler=dbgp
xdebug.remote_host=localhost
xdebug.remote_port=9000

If it is not there, something is messed up with your installation- Mac Ports should do it all for you.

I run my testcases from the command line. Now I need to enable debugging features for it. To save typing, I created a simple script which lets me execute a single php unit test. It looks like:

#!/bin/sh
export XDEBUG_CONFIG="idekey=intellij"
phpunit --bootstrap bootstrap.php --stderr tests/$1

Please mind your directory structure might be different. Also look at the XDEBUG_CONFIG export. It’s basically the key with which your IDE can find your debugging session. I could enter some random string here, as I plan to listen to all debug connections. You might want to go a different path when debugging a live application (not sure if that is a good idea though). Some more docs can be found on the xdebug website.

When we export this variable, we are already ready to debug. IntelliJ has a nice feature which is called “listen to PHP connections”. You’ll find it in the “Run” menu, when you have the PHP plugin enabled. Just click it, create a breakpoint somewhere and the start your test:

./run-test.sh My_Test_Class

IntelliJ would stop at the breakpoint, you are ready to debug. Have fun!