Debugging drush scripts with xdebug and PhpStorm on vagrant in 2016

This is a subject that seems to come up again and again. I figured this out once before, but back then I was using Eclipse, while I am now a PhpStorm devotee. Also, I’ve long since started using Vagrant, which means that every debugging scenario is now “remote”. Usually, this is not a huge issue, but with command line debugging, this presents a bit of a challenge.

Randy Fay has done a nice write-up back in 2013, which covers most of the bases. It does leave one missing link, which seems to have come up only recently; a recent change in drush has broken debugging through xdebug, because it is now using pcntl_exec() to execute the actual script (don’t ask me for the technical details, I haven’t delved into that too much). As is so often the case, Stack Exchange provided the missing piece of the puzzle; it’s possible to circumvent the “decoupling”, that seems to occur due to the pcntl_exec(), by using drush.launcher as the entry point.

As much for my own reference as anyone else’s, these are the key points from both Randy’s post and the SE topic:

  • Set up a “PHP Web Application” for debugging the command line. The sole purpose of this is to be able to provide a path mapping when running the command in Vagrant.
  • Enable xdebug debugging for the command line in your Vagrant box. In my case, this simply meant symlinking the same xdebug.ini from my /etc/php5/cli/conf.d directory as I was using in the /etc/php5/apache/conf.d for web debugging.
  • All executed code needs to be available in the project, including drush. You can accomplish this by e.g. installing drush as a composer dependency (also, remember to execute drush from your project).

The following you will need to do every debugging session:

  • Use PhpStorm’s “Listen for PHP Debug connections” button
  • Set the remote debug client on the command line using (or whatever is the IP-address for your host machine when coming from the Vagrant box; the xdebug.remote_connect_back that is likely in your config will not work for the command line):
    export XDEBUG_CONFIG="idekey=phpstorm remote_host="
  • Set the server configuration. Make sure the name you use matches the server name you configured in PhpStorm:
    export PHP_IDE_CONFIG="serverName=cli"
  • Execute drush by substituting “drush.launcher” for the regular drush command. Make sure you use the drush copy from your project. For example:
    ../vendor/drush/drush/drush.launcher migrate-reset-status posts
This entry was posted in Uncategorized. Bookmark the permalink. Post a comment or leave a trackback: Trackback URL.

One Comment

  1. Mahesh
    Posted 11 November 2016 at 17:22 | Permalink

    Saved me. DIdn’t see
    export PHP_IDE_CONFIG=”serverName=cli”

    In other pages and I spent a couple hours trying to figure it out.

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>