Coming from a .NET background, I love the Visual Studio debugger. I can stop code execution at any time and look at the values of any of the variables. There's none of this dumping huge arrays to the web page and examining the output. I've wanted to set up a debugger for Drupal with Eclipse for a long time now, and setup instructions vary wildly. Here's my take on it.

You will need:

• Ubuntu 10.4: other versions might work, and other Linux distros might work too, but paths and such will differ.
• Eclipse PDT: I was using Helios, having downloaded the all-in-one.

I am also assuming you are running Apache on your local development machine and you want to debug sites locally on this machine only.

Installing XDebug

There's already a package with a version of XDebug compiled especially for Ubuntu, but as pointed out by Heine, this does not allow you to see all the variables in the current scope, so we will need to download and compile this for ourselves. This isn't that scary, so there's no need to worry.

At the time of writing, the latest version of XDebug is 2.1.0, but do check the XDebug downloads page to see if there's a more recent version and grab that instead. First, let's download it and extract it. You'll need a terminal open for this:

Now you'll have a directory containing the source code for the PHP extension, but we need to compile it, which is only a few more commands. If you don't have the phpize command available on your system, you will need to install the php5-dev package (on other flavours of Linux this will be different):

This will produce a file called xdebug.so in the modules directory, so now we'll just copy this to the appropriate path, which is usually /usr/lib/php5/20060613+lfs for PHP 5.2, and if you're on 5.3, it will have 2009 in it.

Now, edit Apache's copy of your php.ini file, which is usually at /etc/php5/apache2/php.ini. Add this section at the bottom:

Save the file, then restart your Apache. Reloading is no good here, so only a full restart will do (which is sudo service apache2 restart in case you need it).

Configuring Eclipse

Fire up Eclipse and let's have some fun with it. Debugging is hugely confusing, but the theory is something like this: the xdebug extension fires up its own local server on your machine and watches Apache like a hawk as it executes PHP, remembering all sorts of things like what variables' values are at various times. We just need to tell Eclipse how to connect to xdebug's local server to retrieve all the juicy information.

I'm assuming you already have a project set up with your Drupal code in it. Some of us work on single-sites, and others on multi-site installs. If you're on a single-site, the entire Drupal directory is probably at the root of your project. If you're using multi-site like us, we have one project for each site, and the root of each project is the site's directory inside drupal/sites/.

It really doesn't matter whether you use either approach here. That is to say that, even if your project only contains the site's code, and no Drupal code whatsoever, you can still debug the Drupal code itself! It took me a while to get my head around that one, but it does work.

Make sure your project is open and ready to work with. Right-click and choose Debug As -> Debug configurations. You will need one debug configuration for each of your Eclipse projects.

In the left pane you will see a load of options. We need PHP Web Page, so double-click this to create a new entry underneath. Give it a name, which can be the same name as your project. Change the debugger to XDebug.

We will need to create a new PHP server. In fact, we need a new PHP server for each Eclipse project, so click New and give it the same name as your project. Enter the URL that is used to access the local development copy of your site.

It really doesn't matter what you put in the File - I just used the root of the project itself here, as long as there is something.

For now, leave Break at First Line checked, because we want it to break at the first line in order to make sure it's running properly. Uncheck Auto Generate for the URL. Enter the URL of your local development site. The first part is greyed out and it's just what you set up earlier under PHP Server but the second part is the path to the root of the site, which, in most cases, will be just /.

Click Apply at the bottom and then take a deep breath. Now, click close, and have a look on the main Eclipse toolbar for the bug icon, which has a little down arrow next to it. Click the bug icon itself to begin debugging.

Debugging

Still with me here? If you've never debugged before, Eclipse will probably prompt about switching to the debugging workspace. When we're debugging, we use a lot of informational panes and tabs we don't normally want to see, so it makes sense to have a separate workspace for this, and just switch back to our main PHP workspace when editing the code.

I didn't actually understand the whole workspace concept, but I just went along with Eclipse and it turned out to work very well, allowing the windows to be arranged in a totally different way just for debugging, so I'd recommend allowing Eclipse to remember your decision by checking the box, then allow Eclipse to switch to the debugging workspace for you.

If everything has worked for you, you will be presented with a copy of Drupal's index.php file, and the debugger will have stopped execution at the first line of proper code in there. This is when you know the debugger works, so you can jump for joy and go get a celebratory cup of coffee (or something stronger) in recognition of this monumental achievement. Click the stop button at the top to end debugging.

Finishing touches

It's really annoying to break at the first line every time we debug, so return to your debug configuration by right-clicking the project and choosing Debug As -> Debug configurations, then unchecking Break at First Line.

Now, you can put breakpoints wherever you like, and once you click that debug button on the toolbar, execution will be halted at each breakpoint so that you can examine exactly what's happening in your code and what the variables say. You can even change the values of the variables, then let the script continue! Have fun...

Troubleshooting

As an anonymous user points out in a comment, sometimes you might see 'waiting for xdebug session' in Eclipse. The vast majority of the time, this is caused when the PHP extension has failed to load. If this is the case, there will be no XDebug session for Eclipse to connect to, and therefore you will never get past this step.

Fortunately it's easy to find out if PHP has XDebug loaded. Just create a PHP file that has the phpinfo() function in it (nothing else is needed except the obligatory php block around it), then visit that page in your browser. Amongst the plethora of configuration information, there ought to be an XDebug section. If there is not, you know that XDebug failed to load, and you ought to look in your Apache logs to find out why not!