New in 4.0: Easier debugging of remote PHP command line scripts

Many of PhpStorm users like to debug their PHP web applications and local command line scripts using our zero-configuration debugging approach due to its simplicity and comfort. This time we would like to announce that since PhpStorm 4.0 you can use this approach for debugging remote PHP command line scripts.

For those who are not familiar with PhpStorm debugging features yet, this type of debugging uses the ‘Listening’ mode and doesn’t require any run configuration or any other extra actions.

‘Start Listen PHP Debug Connections’ action

Zero-configuration debugging is based on analyzing your environment variables. Therefore it is hard to support debugging of remote PHP command line scripts in the listening mode because  there is no definite way to detect the  path mapping configuration to be used for such debug sessions.

You, our users, have asked us to provide a way to debug remote PHP command line scripts using the listening mode (see WI-7906) and we’ve implemented a generic mechanism to specify the path mapping configuration to  use.

To tell PhpStorm which path mapping configuration it should use for a connection from a certain machine you need to set the value of the “PHP_IDE_CONFIG” environment variable to “serverName=SomeName”, where ‘SomeName’ is the name of the server configured in ‘Project Settings | PHP | Servers’. And that is all!

Please note that it will work for any debug connection (both for web applications and command line scripts) because this check has the highest priority in the path mapping detection algorithm.


Here are some possible problems you can encounter when debugging remote PHP debugging command line scripts:

  1. Your PHP CLI interpreter might use another php.ini configuration file than the one installed on the web server. Run PHP with the ‘–i’ option to check which configuration files it actually uses (see the official documentation for details).
  2. (Xdebug only) Please ensure that ‘xdebug.remote_connect_back’ configuration option is disabled. Thanks to Joshua Johnson for the hint.

Download the latest PhpStorm & WebStorm 4.0 EAP. We’d also love to get your feedback in the issue tracker

Develop with pleasure!

This entry was posted in Cool Feature, PhpStorm and tagged , , , , . Bookmark the permalink.
  • Cameron

    I don’t have a “Project Settings” menu item

    • nnmatveev

      You can find ‘Project Settings’ under the ‘File’ | ‘Settings…’ menu item. Thanks for feedback!

  • eisbär

    you need to set the value of the “PHP_IDE_CONFIG” environment variable to “serverName=SomeName”

    where would I set this value, please?

    • Dave

      On UNIX systems:

      export PHP_IDE_CONFIG=’your_server_name’

      It’s handy to append this line to your .bash_profile as well.

      • Dave

        err.. It should be:

        export PHP_IDE_CONFIG=’serverName=your_server_name’

  • khan

    hi have tried the followings:

    export PHP_IDE_CONFIG=”servername=LocalFingi”
    export PHP_IDE_CONFIG=servername=LocalFingi
    export PHP_IDE_CONFIG=LocalFingi

    but always i end up with

    Cannot accept external Xdebug connection: Cannot parse the value of ‘$_SERVER[‘PHP_IDE_CONFIG’]’

    my xdebug log looks like this:

    Log opened at 2012-06-20 12:23:19
    I: Connecting to configured address/port:
    I: Connected to client. :-)

    <- run -i 7

    any idea where i went wrong?

    • Ken Brill

      Just so that others don’t make the same mistake I did, the problem with the three exports above is that it should be serverName and not servername (note the capitol N)

  • Dave

    I don’t know if its just me, but if I don’t have the XDEBUG_CONFIG environment variable set, xdebug completely ignores the fact that it should to connect to PhpStorm for remote debugging. (I had the same experience with Xdebug’s debugclient.) Once it’s set, every single php you run from the command line will be sent for debugging to PhpStorm, even if you didn’t mean to debug them. To overcome this issue I had to untick the “Force break at first line when no path mapping specified” in PhpStorm PHP / Debug settings. As I wanted an easy way to debug while using phpunit I created the following alias:

    alias phpunitdebug=’XDEBUG_CONFIG=”idekey=PHPSTORM” phpunit –stop-on-error –stop-on-failure –verbose’;

    The funny thing is that it doesn’t matter what I set in XDEBUG_CONFIG, PhpStorm always started a debug session. (ie. XDEBUG_CONFIG=1) An environmental variable set this way (right before) a command (like in the alias) is a temporary one, it will be removed once phpunit’s execution stops.

    • Dave

      And a last note just to save you guys from an other couple of minutes of debugging: Dont even try to copy & paste code from this site because the quotes going to be escaped, and PhpStorm will just complain that it couldn’t understand the content of PHP_IDE_CONFIG variable.

  • Greg

    Actually I had it all working fine on LAMP until switched to ZendServer and FCGI. After that the listener fails badly. Pity, pity, pity…