So you’re using Varying Vagrant Vagrants and PhpStorm for local WordPress development. Maybe you’ve heard or read what a great boon PhpStorm is for debugging but you haven’t made it all the way through configuring the project. Maybe you haven’t had time to read the tutorials or you set up a new dev environment seldom enough the steps just aren’t sticking in your long-term memory. If you’re still using var_dump to track down issues, never fear. Let this brief, handy walkthrough guide you to debugging bliss.

Enable Xdebug

The first thing we need to do is turn on Xdebug in our Vagrant environment because it isn’t enabled by default. Open up terminal, cd into your Vagrant folder and:

$ vagrant ssh -c xdebug_on

This command will open an SSH connection to the Vagrant install, execute the xdebug_on command and then close the connection.

Configure Include Path

The CNP dev team often keeps code repositories (themes and plugins) in a location external to our Vagrant install. This also means our projects are external to the WordPress core files. We use a Vagrant Customfile to define synced folders for whatever custom plugins and themes are need for the particular project being worked on. Defining these synced folders allows Vagrant to access the code contained in them even though they may be in a folder separate from the Vagrant install.

Because our project files aren’t located along with the WordPress core files, we need to tell PhpStorm where the WP core files are. To do this, we define an include path.

In PhpStorm, open Preferences with Cmd+,. Go to Languages & Frameworks > PHP. Timesaving tip: search for “include” to narrow down the Preferences menu choices. Add an include path to the htdocs folder of your development site. Example: [path to Vagrant install]/www/my-dev-site/htdocs.

Configure Server Settings

The last leg on our journey to debug nirvana is to configure our server settings.

In PhpStorm, open Preferences with Cmd+,. Go to Languages & Frameworks > PHP > Servers. Another timesaving tip: search for “servers” to narrow down the Preferences menu choices. Click the “+” to add a server. Give the server a name for reference (we typically use the hostname, i.e.: my-dev-site.dev). Enter the Host (i.e.: my-dev-site.dev). Make sure the Port is set to 80 and the Debugger is set to Xdebug.

Now the really important part! Check the box for “Use path mappings.” Below that box, you’ll see a section listing the Project files path and the Include path we defined earlier. In the column labelled “Absolute path on the server,” we have to define the path to those locations as they are on the Vagrant virtual server.

Because VVV is using mapped/synced folders, it sees our site files via the path “/srv/www.” We have to use this in our absolute path definitions and not our local path.

The absolute path for our included WordPress core files should be set to “/srv/www/my-site-dev/htdocs.”

Now, the absolute path for our projects files is dependent on how our project is structured and this speaks a great deal to your own workflow. At CNP, our projects typically contain a single custom theme and at least one custom plugin all kept in a single git repo. The folder structure mirrors WordPress with /themes and /plugins folders.

If the current project is structured in this way, the absolute path for our project files would be:

/srv/www/my-site-dev/htdocs/wp-content

We append “wp-content” onto the path as, well, that’s where WordPress’ themes and plugins folders reside.

Enjoy the Fruits of Your Labor

With our absolute paths defined, we’re ready to start debugging. All that remains is to click the telephone icon in the upper right corner of PhpStorm and enable a breakpoint.

Quick Hit Checklist

Is Xdebug on? If not, cd to the Vagrant install and run this:

  • $ vagrant ssh -c xdebug_on

Do you symlink your themes and plugins to the Vagrant WordPress install?

  • Preferences > Languages & Frameworks > PHP
  • Add an include path to the htdocs folder of your development site. Example: [path to Vagrant install]/www/my-dev-site/htdocs.

Add a Server

  • Preferences > Languages & Frameworks > PHP > Servers
  • Set server name (e.g.: my-dev-site.dev)
  • Set host  (e.g.: my-dev-site.dev)
  • Set port to 80
  • Set Debugger to Xdebug

Configure server path

  • Check the box for “Use path mappings.”
  • Set “Absolute path on the server” to “/srv/www/site-folder-name/htdocs”