Provisioning XDebug ready VMs with Vagrant

I’ve followed this guide by Jeffrey Way to “get off MAMP” and did encounter some difficulties in setting up PHPStorm to debug my code.
Aside for my particular situation of developing and debugging a WordPress plugin the turning point is contained in this article where it reads

Xdebug works by using a protocol known as DBGP over TCP. What makes it slightly confusing, however, is the protocol flow happens in reverse from how most developers are used working: the server makes connections to your “client” (e.g. your IDE). Your debugger actually listens on a port (9000 by default), and Xdebug connects to that. Understanding that makes the setup make a little more sense.

and in this article where a more technical approach is used.

A fresh start

Following the steps outlined in Jeffrey Way’s guide I find myself a working virtual machine that will locally serve a web application I’m developing and want to debug.
The problem is that setting breakpoints on the code as is will not yield any kind of debugging session.
That’s because the virtual machine has not been told:

  1. to use remote debugging
  2. which IP address it should contact for remote debugging

Pointing the right way

What the bash alias in Jeffrey Way’s guide does is downloading a provisioning shell script,, a vagrant file and running the vagrant up command.
Since I need to modify the settings for XDebug configuration I will do that in the provision file,, adding some lines to it to have them added in turn to any XDebug configuration I will provision


Aside for the lines enabling the remote debug the one I had an hard time understanding is the line defining the remote debug host machine IP address: that’s the one the Vagrant machine has assigned to the host machine and will hence contact for debugging.
After that I will be able to enable PHPStorm “Listen for PHP Debug Connections” options as usual to debug the code.

Stream line it

To allow for a repeatable and streamlined process I’ve forked the original alias and to download and use the modified provision file.