Debugging drush scripts with xdebug and PhpStorm on Vagrant

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=192.168.33.1"

• 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