Setting up Xdebug’s remote debug with PHPStorm


As promised in a reddit discussion, I thought I would put up an article on setting up xdebug’s remote debugger with PHPStorm. I have had to assist multiple developers in setting it up and I suspectits because there is a lack of ‘how tos’ on this topic on the interwebs.

I have broken this ‘how to’ into two sections, the server setup and the PHPStorm setup. In my case my server happens to be Debian, so if you are using a different flavour of linux, please adjust as necessary. Likewise with PHPStorm version, my screenshots are from version 7, as far as I can remember, they should differ since version 5.

The server settings

Firstly, check that you have Xdebug installed. My method of checking this is to run the following from terminal:

$ php -i | grep "xdebug"

If you get a result, fanstastic, else you will need to install xdebug, this should do it for you:

$ apt-get install php5-xdebug

Now you will need to change you php settings, so open the file /etc/php/conf.d/xdebug.ini (hopefully using vim and we all know that nano is an inferior editor!!!).

It should contain one line which will be the setting for the zend_extension. After that line add the following settings:

xdebug.remote_autostart = 1

N.B. if you are unsure of what your remote host IP address is, create a php file in which you echo $_SERVER[‘REOMTE_ADDR’]; and run it from the machine you use PHPStorm with. It will output the correct IP address.

Finally, don’t forget to restart you web server (apache in this example):

$ service apache2 restart

The settings in PHPStorm

Go to your PHPStorm settings and make sure that you xdebug port is set to 9000 (if you can not use 9000, I sometimes 9124 else 9125; just make sure it is the same in you ini settings on your server).

PHPStorm Settings Panel
PHPStorm Settings Panel

Save those settings and now go to Run>Edit Configurations… where you will need to add a remote debug instance (see screenshot below)

add remote debug instance
add remote debug instance

You can name this remote debug instance what ever you want, just make sure the IDE key matches what is in xdebug.ini on your server (in this example we used ‘PHPSTORM’).

remote debug instance settings
remote debug instance settings

It likely you won’t have a server setup, if that is the case you can add one by clicking the ‘…’ button. In my project when adding a server, I always need to specify the mappings so you might find you have to do the same.

Finally, once have saved those settings, click on the listen button so that it goes from:

xdebug listening icon
xdebug listening icon


xdebug not listening icon
xdebug not listening icon

If you add a breakpoint now, and load up the page that you want to debug, it should now stop at your breakpoint (I would probably test this with the first line of your index.php to make sure your breakpoint is getting hit!).

Hopefully you will now be a god at debugging the hardest of bugs!

Other hints

If you are not using xdebug, i highly recommend that you turn it off on your server, as if you computer is turned off and you access anything PHP via your webserver it will hang like make as it will be looking for the machine with the IP address specified.

I recommend that you check out xdebug’s profiler if you haven’t already and use it with a tool like kcachegrind else webgrind. Again, I would turn off profiling when not using it as the files it creates on each page load are vast and if you have a small server you may find you run out of storage very quickly!

3 thoughts on “Setting up Xdebug’s remote debug with PHPStorm”

  1. Short solution if you’ve done all of the above without success:

    1) Open port 9000 outbound on the server
    2) Setup port forwarding inbound on the router at the client end

    Long version:

    I’ve found a few sets of instructions like this, and they’re a good step-by-step guide to getting remote debugging working. But none of them seem to mention firewall/port issues.

    I followed all the instructions but could never get the remote server to call back to the IDE on my client. PhpStorm just sat there ‘listening for incoming connection’ which never arrived.

    After several frustrating hours I finally attempted to Telnet out from the server to my client on port 9000 and got a timeout. Ah ha!

    The first part of the fix, for me, was to get my hosting company to open port 9000 outbound. There was no blockage on the server itself, but the hosting company operate their own firewall which was blocking connections out to port 9000.

    After that, I was no longer getting timeouts with Telnet, but ‘connection refused’ instead. This suggested to me that the connection was terminating at some other client on my local network. Basically my router didn’t know where to send the traffic from my server.

    I setup port forwarding on the router for connections inbound to port 9000, forwarding them to the local LAN IP of my PhpStorm client and it instantly started working.

    Hope this saves some a few hours pulling their hair out!

  2. Thanks a lot for the article. It helped me setting it up with the latest PHPStorm EAP. There’s two types however, that confused me a little ;-)

    $_SERVER[‘REOMTE_ADDR’] (Remote)
    and more importantly, debug.remote_host= is missing the x at the start.

    But again, thanks for the great how to.

  3. @Rich – great addition. In my case I found it useful to test the port connections using nc on the linux server and Ncat on the Windows machine running PHPstorm.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>