Debug PHP CLI on Remote Server with Xdebug and PHPStorm

This was a head scratcher when I ran into this yesterday and I thought I would share my solution to the following scenario:

I need to debug PHP Command Line script, located on Remote LAMP Virtual WebServer running in Virtual Box with a Shared Folder, using local PHPStorm 5.0.

The solution:

You first must set PHPStorm to use remote file paths. To set these go to the following:

PHPStorm -> Peferences -> PHP -> Servers

This gives the following display:

PHPStorm Peferences

Replace the Name, Host and Absolute path on the server, to match your own settings. Note keep the Name and Host the same for ease.

Next add some breakpoints in PHPStorm and set it to listen for any debug connections using the listener icon:

Listen to debug connections

Now login to your Remote Server via SSH etc.

You now need to change settings for Xdebug in either xdebug.ini or php.ini depending on how you installed it. You also need to know the IP of the local machine. This can permanently set in the Network Setting of your VM in Virtual Box, so you will never have to change it. In my example the local machine running PHPStorm is:

Now edit the ini file that contains your Xdebug settings and set the following:

xdebug.remote_host =
xdebug.remote_connect_back = 0
xdebug.remote_port = 9000
xdebug.remote_handler = dbgp
xdebug.remote_mode = req
xdebug.remote_enable = 1
xdebug.idekey = phpstorm1

Be aware you might have to change the remote_host and the idekey based on your own environment. To better understand what each option does, see Xdebug Settings

Finally, when running the script you must set the following variables:


PHP_IDE_CONFIG will tell PHPStorm how to map the Remote File Paths to what it sees Locally. Again replace the URL with the Name/Host you set in PHPStorm. Note: You can export this, if your system is only running one site; mine is not.

You can run this inline with your script:


This should send you to PHPStorm where you earlier placed breakpoints.

Happy Debugging!

17 thoughts on “Debug PHP CLI on Remote Server with Xdebug and PHPStorm

  1. Excellent, thanks for this post!

    PHP_IDE_CONFIG was the missing piece in the puzzle for me, without that my break-points were being skipped.

  2. It didn’t work for me until I added xdebug.remote_enable=1. Thanks for the article though, I had it running in no-time thanks to you !

    I use it this way:

    XDEBUG_CONFIG="idekey=PHPSTORM" PHP_IDE_CONFIG="serverName=devserver.local" php -d "xdebug.remote_host=" -d "xdebug.remote_connect_back=0" -d "xdebug.remote_port=9000" -d "xdebug.remote_enable=1" script.php


  3. Thanks, that’s just what I needed! Note: I added these to /etc/environment (in Ubuntu):

    # Variables needed to debug CLI scripts

    export XDEBUG_CONFIG=”idekey-PHPSTORM”

    export PHP_IDE_CONFIG=”serverName=example.local”


      1. Hi Jennifer,

        Having read Blah’s comment and re-reading yours, you are correct that we do not need this in the command. So I have amended the Post to include idekey in the php/xdebug.ini file. However my last reply still stand for PHP_IDE_CONFIG.



  4. I don’t understand where you’re putting the XDEBUG_CONFIG thing. If not in the php.ini, where xdebug.idekey exists, then where?  Are you talking about the actual myscript.php file that we’re coding? Are these constants or something?

  5. Hi,

    Thanks for this post! It doesn’t work with my setup.

    The IntelliJ 13 debugger connects only with Bridged IP. Not with Host-only IP.

    But to be honest I don’t understand the whole part with “PHP_IDE_CONFIG” …

    Setup: Host Windows 8, Virtualbox guest: Ubuntu 14, eth0: Host-only Adapter, eth1: Bridged Adapter.

    xdebug config (/etc/php5/apache2/conf.d/20-xdebug.ini)


    Could you please help me?

    Thanks, Stefan

    1. Hi Stefan,

      There is nothing wrong with using a Bridged network adapter. We quite often find it useful if we are on a private network and need to allow others on that network to see the VM.

      The important thing is that it works which means that its a configuration issue.

      The first thing to look at is the VBox settings for you host only network. If you go into File->Preferences->Network and have a look around you will find details about your host only network.

      Make a note of what addresses are here. I usually get an IPv4 address of and your DHCP server should be set to enabled with addresses in the same 192.168.56.* range.

      Once you have made a note of those settings you can then run `ipconfig` on your windows host to make sure you have an adapter with your IPv4 address. and then (once you have switched back to hostonly) check your VM by running `ifconfig`. All going according to plan you should have an IP address in the 192.168.56.* range.

      If so try switching your config to

      xdebug.remote_host =
      xdebug.remote_connect_back = 0

      Which will force xdebig to connect back to your host machines IP address that we checked earlier with `ipconfig`

      Hope this helps point you in the right direction.


    1. Hi Bishop,

      You would normally put this directly in front of the command your wanting to run. You could also use the `export` command to set it as temporary environment variable if you going to be using it a lot in a single session.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.