Debug PHP in Atom While Using Vagrant

My PHP dev environment is running on a VirtualBox VM and is provisioned via vagrant. How can I use php-debug in Atom on my host machine to debug PHP scripts running on one of my VMs?

Configure xdebug:

Open your php.ini file on your VM and look for the xdebug settings and make sure that you have the following values:

xdebug.remote_autostart=1
xdebug.remote_connect_back=0
xdebug.remote_mode=req
xdebug.remote_log=/tmp/xdebug.log
xdebug.remote_host=10.0.2.2
xdebug.remote_port=9999

Note: you may have multiple php.ini files, e.g. one for cli, fpm, etc… If you do, you’ll need to make sure that you have the xdebug settings above for all environments where you want to use the debugger, e.g. I had to modify /etc/php5/cli/php.ini to use the debugger on the command line and /etc/php5/fpm/php.ini to use the debugger while running PHP scripts with apache.

Restart your web server or any other PHP related services, e.g.

$ sudo service apache2 restart
$ sudo service php5-fpm restart

Install the php-debug package in Atom:

Go to Atom -> Preferences -> Install, search for php-debug and install the package

Configure php-debug in Atom:

Atom -> Preferences -> Packages, search for php-debug and click Settings
Set the PathMaps in the form remote;local. The PathMaps translate the guest/remote path to the local/host path. Let’s assume that you are debugging foo.php and that it can be found on your VM at /var/www/mysite/foo.php and on your host box at /Users/someuser/Documents/vagrant-mysite/foo.php. Your PathMaps config would then be /var/www/mysite;/Users/someuser/Documents/vagrant-mysite.
Server Port: 9999

Start debugging:

Open your target source file in Atom, e.g. /Users/someuser/Documents/vagrant-mysite/foo.php
In the bottom left corner of your Atom screen, click the “PHP Debug” button
Set a breakpoint by clicking immediately left of your target line of code
Visit foo in the browser, e.g. http://example.com/foo.php and this should cause the code to pause in Atom and you should be able to continue debugging
If you configured the php.ini file for your PHP command line settings, you should also be able to debug just by running the script on the guest machine, e.g. php /var/www/mysite/foo.php