Debugging Drush with Eclipse and XDebug

Update 15/4/2017: This is a fairly old post, by now. I've done a more recent post on debugging drush on a setup with PhpStorm and Vagrant.

Drush is a command line tool to interact with the Drupal Open Source CMS (Get it? DRUpal SHell). It is an invaluable tool that many Drupal developers love once they start using it. Another tool I personally love greatly is the XDebug PHP debugger. I use it almost daily to quickly find out what is going on in a PHP website I am working on. It can be a pain to set up, but once you have it, firing up a debugging session is as easy as hitting a button in Eclipse (in fact, it might be the only reason I put up with Eclipse's slugishness; I have yet to find a better integrated experience on the Mac - especially being able to set breakpoints right from your editor is king).

Getting XDebug to work with your local Apache installation can be daunting. Enter Drush. It doesn't work through Apache. Or a browser, for that matter. In short, Eclipse's "PHP Web Page" debugging target is no good. In this post I explain the steps required to get all the XDebug working for Drush commands, just like you sure used to for your PHP sites.

The basics of this post I found in a blog post, when I wanted to set this up some time ago. That blog post may or may not have been this one. I did plan to write up a more detailed explanation, but never got to it. Since then, I had to remove my Eclipse workspace configuration and had to rebuild it, so I thought I'd document the process.

The assumption is that you have XDebug up and running on your local PHP installation. It depends somewhat on your local setup, Google is your friend to get this part worked out. It doesn't really matter which PHP setup it is, as long it's a version Drush is compatible with; unlike the drush command line tool itself, which includes some logic to find a suitable PHP version, we'll be specifying the PHP to use explicitly in Eclipse. I personally use MAMP on Mac OS X 10.7 and I don't go into specifics for other setups. Hopefully, this post is helpful also if you have a different setup, even though the basics should be the same.

The nitty gritty

Right, with all that out of the way, let's get on with it. First of all, make sure you have drush as a project in your Eclipse. If you don't already have it (I can hardly imagine, because you would probably not be here unless you know Drush and want to develop your own Drush commands), you can download the stand-alone Drush distribution from the Drush project page. You can follow the normal installation procedure, the Drush package does not need to be in your default workspace. Once you have Drush installed and working (typing 'drush' a terminal should work), create a new PHP project in Eclipse. Point it to your Drush install.

With the Drush-project present, we'll create a debug configuration. Click on the little dropdown arrow next to the debugger button (which you should be quite familiar with if you use XDebug to debug websites) and click on Debug Configurations...

In the resulting window, double click on PHP Script to create a new PHP Script debug configuration. Name the new configuration "Drush" and select the drush.php file from your newly added Drush project as the PHP File to execute.

Make sure you have a PHP executable defined and selected. I added my MAMP's PHP 5.2, with the following configuration (make sure this PHP has a functioning XDebug install). Also, don't forget to set the debugger to XDebug.

Incidentally, I first had the MAMP PHP 5.3 configured, but while debugging this did not show any variables values. Apparently, this is a known issue for particular combinations of PHP 5.3 and XDebug.

Now, since drush does little by itself, we'll need to include some command line arguments. First of all, we'll want to specify the website to operate on (most drush commands will need a functioning Drupal site). Also, we need to specify the command for drush to execute, including any arguments it might have. So, we go to the tab PHP Script Arguments. Enter the following:

-r ${folder_prompt:Site} ${string_prompt:Command and arguments}

You may use the "Variables" button as an aid to add variables. The nice part of this configuration is that it will remember what you entered before. Should you use multiple string prompts, you will have to change the values around all the time, because it will remember the last value entered among the dialogs.

Click Apply. Click Debug. You should first be greeted with a prompt to select your local Drupal install's root directory. Next, a text popup for the command to execute. And then, stepping/breaking/inspecting goodness. You can set breakpoints in other Eclipse projects and if Drush happens to hit them, it will break as you would expect..