PhpStorm, Xdebug, Vagrant, PuPHPet, and You

I’ve really embraced fully utilizing Vagrant for all of my local development. I don’t use it to replicate client environments, or share a Vagrant box amongst my development team (I work solo) but I find myself aligning with the idea of having this sandbox to work in. Prior to that I used MAMP Pro and it was great for the time being, but Vagrant works better for me now.

One of the biggest draws for me with MAMP Pro initially was getting up and running with Xdebug fairly easily. It involved adding a few lines to my configuration file, but once I figured that out I enjoyed working with it and wrote a post about it for other people.

I want to do the same with Vagrant because using Xdebug has been one of the best decisions for me not only in my own software development, but even more-so when it comes to supporting SearchWP. We’ve all had to sift through code someone else wrote, and it can be a frustrating experience. Having a proper debugging environment can really cut down on the stress of and time devoted to tracking down an issue in code.

Please note that this article is not covering the use of VVV primarily because not everyone uses WordPress. I use VVV for all of my client work, but I decided to set up a second Vagrant box to house all of my support cases for SearchWP. This is another reason I really like using Vagrant; I’m able to keep my client work completely separated from the random code I’ll be checking for various support tickets.

Getting your Vagrant box set up

I’m a big fan of PuPHPet for generating Vagrant boxes, it really helps get you get up and running very fast and has Xdebug integration built in to boot. When configuring your box, pay specific attention to the Xdebug flags you can set, they are very important in making your life easy. Once you’ve made your way to the Languages section of the PuPHPet GUI, pay particular attention to this:

In order to make turning Xdebug on and off easy from within PhpStorm, set xdebug.remote_start = 1. By default it is 0 but setting it to 1 will allow the Xdebug listener toolbar button in PhpStorm to tell your Vagrant box that you want to use Xdebug. You can then proceed through the rest of PuPHPet’s process and generate your final manifest. From there you can follow PuPHPet’s instructions of:

1. Extract the downloaded zip file
2. Open a terminal window and go to the extracted folder
3. Run $ vagrant up and go grab a coffee

Running vagrant up is going to set up a virtual machine exactly as per the specs you just defined in PuPHPet. It will take some time so a coffee break is a good idea. Once it’s up and running, Xdebug will be as well.

Utilizing PhpStorm’s integrated debugger

One of the main reasons I made the switch to PhpStorm over everyone’s favorite text editor is the Xdebug integration. Having breakpoints integrated into the gutter combined with a tool pane dedicated to all things Xdebug along with a single toolbar button to turn Xdebug on and off is very low friction to me. It all adds up to saving time and working faster.

Vagrant is an interesting system as it’s based upon a folder that gets symlinked (synchronized) between your local filesystem and the virtual machine itself. This makes it so you can essentially work on files as though they were sitting on your local hard disk. While this setup makes it a lot easier for us to get up and running with writing code, it introduces a hurdle for debugging.

Since our Vagrant box is technically a remote server, we need to set up Xdebug as though it’s a remote debugging environment. This is complicated by our files being stored locally. Luckily PhpStorm has our back. Since we enabled the xdebug.remote_start = 1 flag when we went through the PuPHPet process, Xdebug is primed and waiting for us to toggle the Xdebug listener toolbar button in PhpStorm, we just need to tell PhpStorm where the server is and which Vagrant folder to watch.

With your PhpStorm project open, navigate to your Preferences pane. With Preferences open, simply search for ‘server’ in the upper left search field:

Navigate to Languages & Frameworks > PHP > Servers and select it. Then click the + button at the top of the Languages & Frameworks details. This will add a new server to PhpStorm.

I would suggest giving the server the same Name and Host just to keep things straightforward. You can leave the Port and Debugger unchanged (they should be 80 and Xdebug, respectively). It is important that you check the Use path mappings box, which will display a directory tree pointing to your current PhpStorm project. In that directory tree, select the root directory of your project (in this case it’s a WordPress install) and directly to the right you will notice a small, hard to see edit icon in the Absolute path on the server column. Click that icon and paste in the full, absolute path to the corresponding project folder on the Vagrant box.

In case that is confusing: in the left column you are selecting the Web root of your project. In the right column you are entering the absolute path to that same folder on the Vagrant box. Remember that Vagrant keeps a local folder on your hard drive in sync with one on the Vagrant box. The absolute path on the Vagrant box is what you will want to enter in the right column. You can SSH into vagrant using the credentials you created when going through the PuPHPet configuration to retrieve the absolute path if necessary.

Once you have added your path mappings, click Apply and OK at the bottom right of the PhpStorm Preferences window, we’re done configuring.

Turn on Xdebug and set breakpoints

Now that Xdebug has been set up and is running on our Vagrant box, and we’ve told PhpStorm how to communicate with it directly, it’s just a matter of adding a breakpoint in our gutter and then turning on Xdebug:

With Xdebug on, code execution will pause at your first breakpoint and allow you to step through the code as you please.

PhpStorm, Xdebug, PuPHPet, and Vagrant

I wanted to post this in hopes of sharing how easy it is to get a fully functional debugging environment set up using some of the many tools available to us as PHP developers. I hope if you haven’t used Vagrant/Xdebug/PhpStorm that you’d give it a shot just to see firsthand how useful real-time debugging can be when compared to a ton of echos, print_r()‘s, and var_dump()s.