Complete step-by-step tutorial for configuring PHPStorm and remote XDebug?

Does a complete tutorial exist for configuring PHPStorm and Remote XDebug?

I'm pulling my hair out.  I already have an existing project that was created before I adopted Vagrant.  I've configured deployment servers, and PHP servers, and Run/Debug Configurations, validated the XDebug configuration and still nothing allows me to run a PHP file for Debugging.  

I'm obviously missing something significant, but I haven't found anything that refers to the entire configuration as a whole to make this work.  Every guide provided by PHPStorm assumes everything is already properly configured before showing you how to use it.

I'm not foriegn to this.  I've had it working with NetBeans in the past, but that was with XAMPP and now I'm using PHPStorm and Vagrant.


Hi there,

Remote debug is not so different from local debug. The biggest mistakes/missing details are:

  • incorrect value for xdebug.remote_host
  • firewall/router blocks incoming connections (it's xdebug who connects to IDE and not other way around)
  • missing/incorrect path mappings (Settings | PHP | Servers)
  • breakpoint is set on such line where xdebug is unable to break (due to the way how PHP itself generates byte code)

If using Zero-config approach (considering that xdebug is installed and configured correctly) IDE should help with setting up path mappings.

These instructions should be enough (at very least it was enough for me):

If it looks like it's working .. but still breakpoints do not hit -- you can always collect logs and dig into them (xdebug specifically):


Thank you so much for all the resources.  I did not find most of those in my searches.  Google only turned up older/less relevent PHPStorm docs.

But I still can't get it to work.

I suspect it's as simple as XDebug not being able to reach PHPStorm but I don't know how to debug that.

I've tried using both xdebug.remote_host and xdebug.remote_connect_back.  I'm positive when using remote_host that I'm getting the IP right because it's--it's the one in the access log and the one I expect to see.

However, the VM is using a configured private network, so the host machine has a virtual adapter.  I don't know that that should matter though.

I'll have to keep digging.


As I suggested already -- debug logs are EXTREMELY useful here,

Set it up, restart apache (if required -- depends how you run php there) and attempt to debug. Then post that log here -- that would be a good start.


It's working now.  Stupid Windows Firewall.

Sorry, I did log xdebug but it showed only that it was not establishing a connection.  But with firewall it was just hanging saying teh connection was open the failed after a couple of minutes.  Without the firewall streams out connection failed messages when PHPStorm is not listening.  So in hindsight I see that this may have been indicative of a firewall issue.

Thank you so much for your help.  I don't think I would have go their otherwise--I was spending too much time looking in the wrong places.  It all makes sense now.


Please sign in to leave a comment.