Configure Xdebug on Netbeans 8 for PHP CLI

XDebug integration with Netbeans has always been flaky for me. It works one minute, and not the next time round. In this post, I’ve outlined some simple and robust steps to get XDebug working with Netbeans 8 on Ubuntu 14.04.

Install XDebug

There are 3 steps to this :

1. Install the Xdebug extension.
2. Configure it.
3. Verify.

To install, run this in your shell : sudo apt-get install php5-xdebug

Modify the `xdebug.ini` file. This is usually in `/etc/php5/mods-available/xdebug.ini`. Set it to :

[xdebug]
zend_extension=xdebug.so 
xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_handler=dbgp
xdebug.remote_host=localhost
xdebug.remote_port=9000
xdebug.remote_autostart=1

Verify that Xdebug has been installed. Run the php -v command and look for the ‘with Xdebug‘ line. Like here:

php -v
PHP 5.5.9-1ubuntu4.9 (cli) (built: Apr 17 2015 11:44:57) 
Copyright (c) 1997-2014 The PHP Group
Zend Engine v2.5.0, Copyright (c) 1998-2014 Zend Technologies
 with Zend OPcache v7.0.3, Copyright (c) 1999-2014, by Zend Technologies
 with Xdebug v2.2.3, Copyright (c) 2002-2013, by Derick Rethans

Make sure you see it, or Xdebug has not been installed and the rest of this tutorial won’t work for you!

Here everything so far in copy-paste form :

sudo apt-get install php5-xdebug;
sudo sh -c "echo '[xdebug]
zend_extension=xdebug.so 
xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_handler=dbgp
xdebug.remote_host=localhost
xdebug.remote_port=9000
xdebug.remote_autostart=1' > /etc/php5/mods-available/xdebug.ini" ;
php -v | grep Xdebug

Configure Netbeans

Now configure Netbeans :

1. Click on Tools > Options > PHP > Debugging
2. Check ‘Stop at First Line‘ and ‘Show Debugger Console‘

The ‘Stop at First Line’ option provides us quick feedback on whether the hook up worked. Otherwise you need to set a breakpoint in your code for it to actually stop there. Once the setup has been verified you can uncheck this option.

Setup a Debug Session

To run a debug session you need to create a ‘Run Project’. This is just a configuration setting that tells Netbeans how to start your code properly with the debugger. I’m using a Symfony project, so I’m going to demonstrate debugging a test case with PHPUnit :

1. Click on Run > Set Project Configuration > Customize
2. Click ‘New‘. Give a name, say ‘PHPUnit’
3. Run As : Set it to ‘Script (run in command line)‘
4. PHP Interpreter : Use the default, this is usually `/usr/bin/php5` on Ubuntu.
5. In Index File, set the full path to your phpunit.phar file.
6. Press Ok.

Debug!

This is the easiest part. If you’ve done the above correctly you will be able to see Netbeans stop at the first line it finds. To debug a file :

1. Click on the file and press ‘Ctrl + Shift + F5’. Or Right-click and click ‘Debug’
2. [If Netbeans complains the phpunit.phar file is too large, press ‘No’.]

That’s it! From here you can :

1. Create a breakpoint in your file.
2. If your breakpoint is in the run path, Netbeans will now stop at your breakpoint.
3. You can watch all the variables declared until that point in the ‘Variables’ tab, and inspect their values at that point. You can also see the stack trace so far. Really useful stuff!

Happy debugging!