Debug command line scripts with PhpStorm 2.1

Posted on by nnmatveev

Hello everybody,

Recently, we have been often asked to provide a detailed guide in debugging command line scripts. And finally here you are!

Currently PhpStorm supports two debug extensions, namely Xdebug and Zend Debugger. Before start debugging command line scripts you need to configure your development environment: the PHP interpreter and PhpStorm.

Configuring PHP interpreter

Please, follow the links below to find detailed instructions in configuring Xdebug or Zend Debugger:

Configuring PhpStorm

First of all, you need to tell PhpStorm which  interpreter to use for launching scripts.

Select path to PHP home

Next, you need to specify the extension you are going to use for debugging.

Select PHP debug extension

Now, let’s go ahead and start debugging!

Setting Breakpoints

Click the left gutter area at the line where you want to toggle a breakpoint.

Setting a breakpoint

Debugging Using Run Configurations

In PhpStorm, script execution capabilities are based on the ‘Run Configuration’ concept. See details in the PhpStorm on-line help:

PhpStorm enables using numerous run/debug configurations. Each run/debug configuration represents a named set of run/debug startup properties. When you perform run/debug operations with PhpStorm, you always start a process based on one of the existing configurations using its parameters.

PhpStorm comes with a number of pre-defined default run/debug configuration types for the various running and debugging issues.

PhpStorm features a dedicated ‘PHP Script’ run configuration for debugging command line scripts. Creating a run configuration from a PHP script context menu is as easy as a mouse click: just open the context menu and choose the ‘Create yourscriptname.php’ item if you need to specify a custom working directory or any script parameters.

'Create script.php' context menu item

Specify the custom working directory, the script parameters or enable the ‘Break at the first line’ debug mode (all these settings are optional), and click ‘OK’.

'PHP Script' run configuration settings editor

The new run configuration is saved. To start debugging, click the ‘Debug’ button on the toolbar.

'Debug' action on toolbar

If you don’t need any additional settings, just choose the ‘Debug’ item (by default, the working directory is the parent directory of the script).

Debug 'Create script.php' context menu item

As soon as the script execution stops at the breakpoint, open the ‘Debugger’ tab in the ‘Debug’ tool window. Examine the values of variables in the current frame or add a new expression to the list of watches, if necessary.

'Debugger' tab

The results of the script execution are displayed in the ‘Console’ tab of the в ‘Debug’ tool window.

'Console' tab

To customize an existing run configuration or create a new one manually, choose ‘Edit Configurations’ from the run configurations pop-up menu.

'Edit Configurations' menu item

Add a new ‘PHP Script’ run configuration.

'PHP Script' item in 'Add New Confiuguration' popup menu

Or edit the existing one.

Debug using ‘listen debug connections’ button

Many of you have been fond of debugging scripts on the server using the ‘Start Listen PHP Debug Connections’ button.

'Start Listen PHP Debug connections' button

Unfortunately, PhpStorm 2.1 does not support this mode for debugging CLI scripts and displays the following warning:

'Cannot accept external Xdebug connection' warning notification

The problem has been solved in PhpStorm 3.0. So if you are keen on experimenting you can start using this CLI scripts debugging mode right now. We are happy to inform you that PhpStorm 3.0 EAP has been launched.


You may happen to get the following error message after script execution finishes: ‘Debug connection with Xdebug was not established’. This means that PhpStorm has not received an incoming connection from the debugger and the debug session has not been established. Most likely, the PHP interpreter is not configured correctly, for example, no debug extension is installed at all.

'Debug connection with Xdebug was not established' error notification


Develop with pleasure!

Comments below can no longer be edited.

8 Responses to Debug command line scripts with PhpStorm 2.1

  1. Seth Thornberry says:

    October 6, 2011

    I actually have remote server CLI debugging working.
    It isn’t too hard.
    I added these aliases to my .bashrc so I could turn debugging on and off:

    alias bugOn="export XDEBUG_CONFIG=\"idekey=phpstorm remote_host=`expr "$SSH_CLIENT" : '\(^[0-9.]*\)'`\";export SERVER_PORT=80;export SERVER_NAME=[your server host name here]"
    alias bugOff="unset XDEBUG_CONFIG;unset SERVER_PORT;unset SERVER_NAME"

    • Seth Thornberry says:

      October 6, 2011

      in case it isn’t clear in the alias — it dynamically sets the debug host to whatever host you’ve ssh’d in from

      • nnmatveev says:

        October 11, 2011

        Thanks for sharing!

    • Seth Thornberry says:

      October 11, 2011

      The PHPStorm 3 EAP needs an extra export. Add ;export REQUEST_URI=[any URI here] to the end of the bugOn alias and ;unset REQUEST_URI to the end of the bugOff alias

    • Michael Pelz-Sherman says:

      October 12, 2011

      Thanks, this worked for me! I do consider it “hard” though, if only because it’s not documented and requires knowledge of how xdebug environment variables work. 🙂

  2. Zyava says:

    October 11, 2011

    Please update your Xdebug installation guide. In case of PHP 5.2 zend_extension_ts should be used, at least for me zend_extension doesn’t work when zend_extension does.

    • nnmatveev says:

      October 12, 2011