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

drupalplanet