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.
Click the Start Listening for PHP Debug Connections button on the toolbar/the status bar 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.

Start the script with debugging using PHP command-line switches

Launch PHP with the following command-line options:
php -dxdebug.mode=debug -dxdebug.client_host=127.0.0.1 -dxdebug.client_port=9003 -dxdebug.start_with_request=yes path/to/script.php
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

Start the script with debugging using an environment variable

Set an environment variable that configures Xdebug:
- For Windows:
  set XDEBUG_MODE=debug& set XDEBUG_SESSION=1
  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_MODE=debug XDEBUG_SESSION=1
  export XDEBUG_CONFIG="remote_enable=1 remote_mode=req remote_host=127.0.0.1 remote_port=9000 remote_connect_back=0"
Start the script normally:
php path/to/script.php
Optionally, you can use Xdebug's remote_autostart (for Xdebug 2) or start_with_request (for Xdebug 3) setting to always start a debugging session for every script that is run.

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: 17 January 2023