Not all PHP applications are web applications. Many of us write scripts that run in the PHP CLI. Our own command line tools, our own daemons, a message queue processing application and other types of applications typically run from the command line. In this tutorial, we'll see how we can debug PHP CLI scripts with PhpStorm.

There are various ways to start a debugging session. We can start a session from within PhpStorm and make it start our script and attach the debugger to it. Another way is to let PhpStorm listen for incoming debugger connections and start the script outside the IDE. We'll have a look at both options.

Be sure to check the other tutorials about debugging PHP code with PhpStorm to learn more, including troubleshooting tips and advanced debugging techniques.

Create a new Run/Debug configuration using the Run | Edit Configurations menu. Next, add a new configuration of the type PHP Script and provide the required parameters, such as the script to be executed.

Click Save to store the Run/Debug configuration.

We can let the IDE generate a Run/Debug configuration for a script for us. From the Project tool window, use the Debug | <script name>.php context menu (make sure to pick the one which has a PHP icon). We can also open our script in the editor and press Alt+Shift+F9 (Ctrl+Alt+D on Mac OS X) and select the script to be debugged.

The IDE will launch the script with the debugger enabled, and open the debugger tool window.

Continue debugging using the tools and techniques outlined in Using the PhpStorm Debugger.

Xdebug has various configuration options which we can use 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 way will be to set an environment variable so we don't have to provide the -d switches all the time.

Using PHP command line switches

To start our script with debugging we have to:

1. Set an environment variable that would tell XDebug to connect to IDE:

   Windows: set XDEBUG_CONFIG="idekey=123"   Linux / Mac OS X: export XDEBUG_CONFIG="idekey=123"

   Here idekey should have a random value.

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

   You might use 10.0.2.2 instead of 127.0.0.1 with Vagrant (see related SO question).

    

Using an environment variable

To start our script with debugging, we can set an environment variable that configures Xdebug:

Windows:
set XDEBUG_CONFIG="remote_enable=1 remote_mode=req remote_port=9000 remote_host=127.0.0.1 remote_connect_back=0"

Linux / Mac OS X:
export XDEBUG_CONFIG="remote_enable=1 remote_mode=req remote_port=9000 remote_host=127.0.0.1 remote_connect_back=0"

Next, we can start our script like we would normally do:

php path/to/script.php

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

First, we have to set the QUERY_STRING environment variable:

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

Linux / Mac OS X:
export QUERY_STRING="start_debug=1&debug_host=127.0.0.1&no_remote=1&debug_port=10137&debug_stop=1"

Next, we can start our script like we would normally do:

php path/to/script.php

Windows:
set PHP_IDE_CONFIG="serverName=SomeName"

Linux / Mac OS X:
export PHP_IDE_CONFIG="serverName=SomeName"

If the script that is being debugged is not a part of the project that's open in PhpStorm, the IDE will still open the script in the editor and pause execution at the first statement. This makes it possible to quickly debug any PHP CLI script, even if we don't have a PhpStorm project for it yet.