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:

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!

Bookmark and Share

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

  1. Richard

    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. Bert-Jan

    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:


  3. Jennifer Simonds

    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. Richard Nicol Post author

        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. blah

    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?


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 class="" title="" data-url=""> <del datetime=""> <em> <i> <q cite=""> <strike> <strong> <pre class="" title="" data-url=""> <span class="" title="" data-url="">