Remote debugging with PHPStorm and Xdebug

Remote php application debugging, also works with vagrant!

Posted by on January 21, 2016 Remote debugging with PHPStorm and Xdebug

Nowadays we are working with virtual machines or remote environments by default. We have big development cycles, working with project teams on compley solutions. We are using versioning like git. We just need to fit these modern development standards.

One of these standards is remote debugging.

Let’s assume we have a development, staging and production environment. An error occurs on staging or production for any reasons. First of all, this error should not happend, but exists. The written code is still correct. And again the error should not exist. At this point, we want to debug and solve this problem. Smart as Sherlock Holmes - with a minimum amount of time and a maximum of efficiency.

Xdebug is perfectly good integrated in PHPStorm. Let’s debug on any remote system, including Vagrant - which is still remote on your local machine.


I assume an Ubuntu / Debian os, but you could still adapt for any OS. I use the vagrant Scotch Box 2.5 as very good working a LAMP stack.

Prepare Xdebug on remote system

We need to install xdebug

sudo apt-get install php-xdebug

and configure it.

nano /etc/php5/apache2/conf.d/20-xdebug.ini

Add following lines to configuration file (zend_extention should be already configured):

xdebug.remote_enable = on
xdebug.remote_connect_back = on

Gratulations, we finish the easy part.

Get PHPStorm ready for Xdebug and remote debugging

Deployment Server

We need to tell PHPStorm were our root location is and how to connect to this location.

  • select File | Settings > Build, Execution, Deployment | Deployment
  • click green ‘+’ and choose Type ‘SFTP’ and a name associated with vhost ServerName
  • choose conection settings as follows
SFTP Host:
Port: 2222
Root path: <click auto detect!!!>
User name: vagrant
Auth type: Password
Password: vagrant

---- some other configuration ----

Webserver url: <associated with vhost ServerName !!!!>
  • choose mappings tab
  • Leave all options as is, expect the following:
    Deployment path on server '<given servername>': /var/www

Remote interpreter

PHPStorm needs to no

  • select File | Settings > Language & Frameworks | PHP
  • click […] beside interpreter and after that green ‘+’ and choose ‘remote’
  • choose SSH Credentials and configure as follows
Host: Port: 2222
User name: vagrant
Auth type: password
Password: vagrant

---- some other configuration ----

PHP executable: /usr/bin/php5


We need to configure mappings on remote server, to find sources and stop on breakpoints on our local system.

  • select File | Settings > Language & Frameworks | PHP | Servers
  • click green ‘+’ and add following:
Name: any name associated with vhost ServerName 
Host: (configured ServerName in vhosts!): in my case
Port: 80
Debugger: xdebug

For Vagrant

root folder (e.g. /var/www) should be associated with mounted folder in Vagrantfile.

config.vm.synced_folder ".", "/var/www", :mount_options => ["dmode=777", "fmode=666"]


If you use an further folders folder like laravel public for index.php and assets, create an additonal mapping for this location: /var/www/public


  • select Run | Edit configurations
  • click green ‘+’ and choose PHP Web Application

Let’s have fun

Create a breakpoint by click on any linenumber with a method or other control structure like if.

Default debugging

You are now debug with clicking on Run > Debug.

Smart debugging

In PHPStorm activate remote listening for debug connections by clicking Run > Start listening for PHP debug connections

Or you could use these convenience snippets to enable debugging directly within your application or as shortcut in your browser:


It’s a lot work, but it is a well proofed configuration. I used this for many projects in production and while develop software, websites with wordpress or shops with magento. It still works fine.

If you have questions, improvements or something else, just write a comment or tell me at twitter.