Setting up XDebug on a Vagrant machine and figuring out how to set up PHPStorm on your host machine so that everything works smoothly can seem daunting, but it’s really easy! I’m going to go ahead and assume that you already have a development environment (LAMP, or other).

Note: unless otherwise specified, you should follow these steps on your vagrant machine.

1. Download XDebug. If you have git, it’s as easy as:

   git clone git://github.com/xdebug/xdebug.git

2. Follow the installation instructions for xdebug.
3. On my vagrant box I copied modules/xdebug.so to /etc/php5/xdebug.so, so that is what I’ll be using for this guide.
4. Open up your php.ini file using your favorite editor (I prefer vim!). On my machine it is located at /etc/php5/apache2/php.ini, but if you don’t know where it is you should be able to run “locate php.ini” to find it.
5. Go all the way to the bottom, and add the following to your php.ini:

   zend_extension="/etc/php5/xdebug.so"
   xdebug.remote_enable=1
   xdebug.remote_host=10.0.2.2
   xdebug.remote_handler=dbgp
   xdebug.remote_port=9000
   xdebug.remote_autostart=0

6. Note: I have 10.0.2.2 in my example, but this should be whatever IP the vagrant box recognizes your host machine as. If you’re not sure, run vagrant ssh on your host machine, and you will see something like “Last login: Thu Mar 6 04:17:44 2014 from 10.0.2.2″ when you log in to your vagrant machine.
7. Restart your webserver, and php-fpm if you use it.
8. If you don’t have one already, install an xdebug extension in your browser of choice on your host machine. Select PHPSTORM as the IDE Key.
9. Activate your debugger extension in your browser.
10. Under “Run” in PHPStorm, select “Start Listen for PHP Debug Connections” – it looks like a phone with a bug going into it.
11. Set a breakpoint somewhere in your code. Preferably index.php or a bootstrap file of some sort – you want it to be something you know will run. In PHPStorm that is as easy as clicking the margin next to a line of code. You will see a red circle appear and the line will highlight.
12. Navigate to the site you are trying to debug.
13. You should now see a window that says “Incoming Connection from Xdebug” – select the file you set the breakpoint in, and click accept.
14. You should now be able to debug effortlessly!

If you’re not sold yet on why you should be using a debugger, here’s a few reasons I personally use it:

• I don’t want to litter var_dump() calls all over my code. It’s too easy to forget where you put them all, especially if you don’t have something that’s tracking your changes. Plus, say you want to know the value of 6 different variables at one particular point in the code… and again 5 lines later. It’s just a pain in the butt.
• Sometimes, when something isn’t working correctly, and reading the code isn’t giving me any indication, it’s nice to just be able to step through my code, and watch what conditions are met and how the variables are changing. This is pretty much impossible without a bunch of var_dump() and exit calls if you don’t have a debugger.
• You can demonstrate very easily that your code works. It makes unit testing a breeze.
• Wondering if a particular function gets called? Just set a breakpoint and see if you hit it. No more wondering.