Instructions on how to step through your PHP code with XDebug seem to be an unholy mess online. After an hour of tinkering in Ubuntu 12.04 to get it working, I’ve come up with the ten steps listed below to get the combination of Ubuntu, Nginx, PHP-FPM, XDebug and Aptana Studio 3 working together. Here’s hoping this helps someone else out there.

1. Install php5-xdebug:

sudo apt-get install php5-xdebug

2. Edit the xdebug configuration file /etc/php5/fpm/conf.d/xdebug.ini , most notably changing the default port to 9001 as PHP-FPM itself runs a daemon on port 9000. We also change the log file location to /var/log/xdebug (remember to create this folder):

xdebug.profiler_output_dir=/var/log/xdebug
xdebug.profiler_enable_trigger=1
xdebug.profiler_enable=0

xdebug.remote_enable=true
xdebug.remote_host=127.0.0.1
xdebug.remote_port=9001
xdebug.remote_handler=dbgp
xdebug.remote_autostart=0

3. Restart PHP-FPM:

sudo /etc/init.d/php5-fpm reload

4. In Aptana Studio 3, we’ll start by ensuring that Aptana recognizes XDebug as being installed as a debugger on the system. Go to Window > Preferences > Aptana Studio > Editors > PHP > Debug. Ensure that under Installed Debuggers, XDebug is listed on port 9001.

5. While still in the Preferences window, go to General > Web Browser and change the option to Use external web browser. Leave Default system web browser marked.

6. Close the Preferences window and go to Run > Debug Configurations… Right-click PHP Web Page and select New.

7. Name your configuration whatever you’d like (localhost if you’re lacking ideas). Ensure that Server Debugger is set to XDebug. Create a new PHP Server by clicking the + button, and ensure that you set the Base URL and Document Root properly for the website you are trying to debug.

8. Almost done! We now need to Xdebug Helper in the Google Chrome browser. After it’s installed, enable it on your locally viewed web page by clicking the bug icon until it changes colour to green (if you hover over it, it will inform you that it has debugging enabled).

9. Let’s switch back to Aptana Studio 3. Under Window > Perspective, switch to Debug. We left the “Break on first line…” option under Window > Preferences > Aptana Studio > Editors > PHP > Debug, but you can just as easily double-click in the margin beside any line in your PHP script to add a breakpoint at that location. Navigate to a page that will execute that PHP script and watch as execution halts and your debugger steps in, giving you the ability to inspect variables or control execution at will.

10. Inspect the value of any variable quickly by adding the Expressions window while in Debug mode at Window > Show View > Expressions. Pop in a variable such as $page and press Enter to see the value immediately.

Need to switch back to regular coding view? Under Window > Perspective, switch to Web. Bear in mind that even outside of the Debug perspective your debugger will be active – click the bug icon in Chrome until it is grey to disable activating XDebug.