The definitive remote debug and unittest with PHPStorm guide: part 1

This post is part of the guide on how to setup your PHPStorm for remote debugging and unit testing. Click here for the beginning of this guide.

Intro: Short introduction on my environment

Before we start, i’ll explain a bit about my current setup. I don’t have ANY development running locally and this keeps my box free of all clutter. Especially on systems like Mac OSX, this turns quickly into a homebrew/macport dependency hell, with half installed tools and whatnot.  Even if you manage to get your tools running correctly, after a while your system will be cluttered with things you don’t need and at best take up disk space / memory, but worst case scenario it will mess with newer tools you’re installing, or just leaving other applications hanging in limbo.

I keep my system clean and all development is done through virtual machines which mostly are maintained through Vagrant/Virtualboxes. I do have a single “main” virtual machine that I use for everything that’s simple LAMP. These are mostly the smaller project, things I want to do quickly and do not want to spent time on setting up complete new environments. It’s a simple setup but because I use it a lot, i want it to be as fast as possible to get a new project up and running. Most larger projects, or projects running for customers are normally done in separate virtualboxes maintained with vagrant. If you’re not interested in how this system is setup, you can skip this part and continue directly with the vagrant chapter below.


On my “main” server I (still) use apache with a virtual document root. If you run nginx, you probably have an easier setup than I have, but i reckon with the same outcome. I have my system setup to have multiple hosts, all running on different document-roots, but without setting up all those environments. This makes my life much easier: I only need to create a new directory at my server under /wwwroot, and this directly is automatically shared as a domain from the web server.

To give you an example: my server runs at debian.virtualbox.local (the .local domain can have issues when running on a OSX system, but I haven’t had any problems with it, if you have, just rename this to .dev or something). Because of the fact that I’m using virtualdocumentroot, the website http://bigproject.debian.virtualbox.local” actually points to the directory /wwwroot/bigproject/public. The site http://foo.debian.virtualbox.local  points to /wwwroot/foo/public. I’m using the “public” here because many frameworks have a separate web-folder that should be accessible from the web server, while everything else isn’t. This allows me for instance to setup a symfony2 project inside /wwwroot/symfony2project, and place all the web-files inside /wwwroot/symfony2project/public. Unfortunately, symfony2 does not use ‘public‘ as their public directory, but rather the directory ‘web‘, so I normally symlink this ‘web’ directory to ‘public’. If you do lots of symfony2 it might make sense to change your apache configuration with your virtualdocumentroot to /web instead.

Starting a new project could be done through PHPStorm (File | New Project), or manually on your development server:

and we can just browse to http://<myproject>.debian.virtualbox.local

My local machine runs a DNS server in which I route everything from *.debian.virtualbox.local to, which is my debian machine. Another 10 seconds won by not having to change /etc/hosts!



If you are running a simple system, or just want to use vagrant for this guide, things are still pretty much the same. Your virtual machine created with vagrant will have a webserver running and is accessible by your local browser. You will have a source directory on your local machine that gets shared with this virtual machine, most probably through the /vagrant directory.


Path mappings

One things that will be very important through the course of this guide are path mappings. On my dev-machine I have samba running which allows me to share directories locally. The samba share i’m using is called [www], which means that OSX normally mounts this automatically on /Volumes/www.

For now, it’s important to remember that the LOCAL /Volumes/www path maps to the REMOTE /wwwroot path. This will be PHPStorm’s way of knowing which file locally maps to which file remotely.

If you work on Vagrant machines, you clone your project into a certain directory (I use a separate /Volumes/Code partition for this), and vagrant shared this directory with the /vagrant inside your virtual machine. This means your path mapping will be /Volumes/Code/myproject => /vagrant.

Again: this is an important aspect later on!



Hurrah! The first chapter is completed: You know a bit more about path mappings so now we can dive into some deeper waters. Find out how we can easily setup autocompletion for unit-testing in the next chapter.


  • […] reason for this are path mappings (i told about path mappings in the first chapter). It can find its file inside the public webroot, and if you have other files, those will probably […]

  • […] [Article] The Definitive Remote Debug and Unittest with PHPStorm Guide […]

  • Joshua Thijssen is an all-round consultant and trainer. His daily work consists of maintaining code bases, working on different projects and helping other to achieve higher standards in both coding and thinking. He is author of the PHP|Architect book "Mastering the SPL library" and the Symfony Rainbow Series, founder of the Dutch Web Alliance and regular speaker at national and international conferences. Find him on twitter at @JayTaph, or read his personal blog at

    Dutch Web Alliance