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..

This entry was posted in Web and tagged , , , , . Bookmark the permalink. Post a comment or leave a trackback: Trackback URL.


  1. Tyler
    Posted 24 April 2012 at 00:37 | Permalink

    I found I also had to start Eclipse from terminal, rather than running it as an Mac App. Reason is Eclipse doesn’t pick up ~/.profile variables, including $PATH which contains location to mysql. There’s some recommendation to source at /etc/profile instead, but that doesn’t work for me either.

    So if anyone else is having this problem, what works for me is running

    sh /Applications/eclipse/eclipse
  2. Posted 1 July 2012 at 11:34 | Permalink

    Probably completely depends on your AMP setup. I use MAMP, which has been fairly troublefree. The above works perfectly for me without having to start Eclipse from the command line.

  3. Pieter
    Posted 4 July 2013 at 16:43 | Permalink

    make sure to NOT have xdebug launch in the background, otherwise Eclipse (Kepler at least) might stall.

    so make sure to check ‘Launch in background’ at the bottom of the ‘Common’ tab of the debug config window (–540×431.png )

  4. Burke
    Posted 7 May 2014 at 11:38 | Permalink

    Thanks Eelke – a good post to get me started on debugging Drush. Now I am kind of stuck and seeking some advice because from Eclipse my Drush doesn’t seem to see settings.php while I’ve provided the –root argument. I have a fairly long text to describe the situation so I post it on Drupal Answers. Could you please maybe checkout this post on Drupal answers and see if you have any suggestions? Many thanks in advance.

  5. Jorge
    Posted 28 June 2014 at 13:31 | Permalink

    After the first popup (site location), and the drush command arguments, eclipse runs and terminates even if I set a breakpoint in drush_main() but doesn’t provide any output on the console, only error message when command is malformed.

    I was careful enough to make sure xdebug is also enabled in the CLI’s php.ini

    xdebug log: I:

     Connecting to configured address/port: localhost:9000.
    I: Connected to client. :-)
    -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="" status="stopping" reason="ok"></response>

    Any idea guys? Thanks!

  6. Posted 23 November 2016 at 21:47 | Permalink

    I have been doing Android development in Eclipse and released few games, have 1 Drupal Hardware review website for which I can use this article’s information to find some loopholes in the website and fix them.

One Trackback

Post a Comment

Your email is never published nor shared. Required fields are marked *

You may use these HTML tags and attributes <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>