Starting a debugging session from the command line

You can start debugging a PHP CLI script from the command line, having PhpStorm listen for incoming debugger connections.

Set the breakpoints where necessary.
On the toolbar, click the Start Listening for PHP Debug Connections button or select Run | Start Listening for PHP Debug Connections from the main menu.
Start the script with debugger options depending on the debugging engine you are using - Xdebug or Zend Debugger.

Start a Script with Xdebug

Xdebug has various configuration options which can be used to let the PHP interpreter reach out to PhpStorm. These parameters have to be passed to the PHP interpreter using the -d command line switch. A more convenient is to set an environment variable you do not need to provide the -d switches all the time.

Do one of the following:

Launch PHP with several switches:
php -dxdebug.remote_enable=1 -dxdebug.remote_mode=req -dxdebug.remote_port=9000 -dxdebug.remote_host=127.0.0.1 -dxdebug.remote_connect_back=0 path/to/script.php
php -dxdebug.mode=debug -dxdebug.client_host=127.0.0.1 -dxdebug.client_port=9003 -dxdebug.start_with_request=yes path/to/script.php
For Xdebug 2, set an environment variable that configures Xdebug:
- For Windows:
  set XDEBUG_CONFIG=remote_enable=1 remote_mode=req remote_host=127.0.0.1 remote_port=9000 remote_connect_back=0
- For macOS / Linux
  export XDEBUG_CONFIG="remote_enable=1 remote_mode=req remote_host=127.0.0.1 remote_port=9000 remote_connect_back=0"

Start a script with Zend Debugger

Zend Debugger has various configuration options which can be used to let the PHP interpreter reach out to PhpStorm. These parameters have to be passed to the PHP interpreter using an environment variable:

                    set QUERY_STRING=start_debug=1&debug_host=127.0.0.1&no_remote=1&debug_port=10137&debug_stop=1
                

                    export QUERY_STRING="start_debug=1&debug_host=127.0.0.1&no_remote=1&debug_port=10137&debug_stop=1"
                

Configure path mappings

To tell PhpStorm which path mapping configuration should be used for a connection from a certain machine, set the value of the PHP_IDE_CONFIG environment variable to serverName=SomeName, where SomeName is the name of the debug server configuration defined on the Servers page, see Create a PHP debug server configuration. Depending on the operating system you are using, set the value in one of the following formats:

set PHP_IDE_CONFIG=serverName=SomeName

export PHP_IDE_CONFIG="serverName=SomeName"

Troubleshooting

The debug server configuration is not specified through the PHP_IDE_CONFIG environment variable. In this case, PhpStorm detects the host and port from $_SERVER['SSH_CONNECTION'] and suggests to create a new debug server configuration if it doesn't exist. This works for all connections through ssh even without a tunnel.
The debug server configuration is not specified through the PHP_IDE_CONFIG environment variable and $_SERVER['SSH_CONNECTION'] is not defined. In this case, a warning is displayed with a link to the instruction in specifying the debug server configuration through the PHP_IDE_CONFIG environment variable.
The debug server configuration is specified through the PHP_IDE_CONFIG environment variable but a wrong format is used, PhpStorm displays an error message with the instructions.
The PHP_IDE_CONFIG environment variable is configured properly, but the specified debug server configuration doesn't exist, PhpStorm displays a warning with a link to the Servers page.

Last modified: 08 March 2021