PhpStorm
 
2022.3
Shortcuts: Windows
Get PhpStorm
  1. Debug with PhpStorm: Ultimate Guide
  2. PHP debugging session
  3. Zero-configuration debugging
  4. Starting a debugging session from the command line

Starting a debugging session from the command line

Last modified: 17 January 2023

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

  1. Set the breakpoints where necessary.

  2. Click the the Start Listening for PHP Debug Connections button 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.

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

Start the script with debugging using an environment variable

  1. Set an environment variable that configures Xdebug:

    • For Windows:

      set XDEBUG_MODE=debug& set XDEBUG_SESSION=1

    • For macOS / Linux

      export XDEBUG_MODE=debug XDEBUG_SESSION=1

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

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

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.