Debugging a PHP CLI script
PHP applications are not always web applications. Various command line tools, daemons, message queue processing applications and other types of applications typically run in the PHP CLI. 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. Alternatively, you can let PhpStorm listen for incoming debugger connections and start the script outside the IDE. We'll take a look at both options.
Before you start debugging, make sure that you have a debugging engine installed and configured properly. PhpStorm supports debugging with two most popular tools: Xdebug and Zend Debugger. These tools cannot be used simultaneously because they block each other. To avoid this problem, you need to update the corresponding sections in the php.ini file as described in Configuring Xdebug and Configuring Zend Debugger.
To open the active php.ini file in the editor:
In the Settings/Preferences dialog (Ctrl+Alt+S), click PHP under Languages & Frameworks.
On the PHP page that opens, click next to the CLI Interpreter field.
In the CLI Interpreters dialog that opens, the Configuration File read-only field shows the path to the active php.ini file. Click Open in Editor.
Starting a debugging session from PhpStorm
To start debugging a PHP CLI script from within PhpStorm, perform the following steps.
Create a Run/Debug Configuration
PhpStorm uses Run/Debug configurations to execute a script from within the IDE. A configuration can define additional arguments for the PHP interpreter as well as launch other commands prior to starting our script. We will need a Run/Debug configuration to start the debugger from within PhpStorm.
To create a Run/Debug configuration for a PHP script manually
Create a new Run/Debug configuration using themenu.
Add a new configuration of the PHP Script type and provide the required parameters, such as the script to be executed.
Save the created Run/Debug configuration.
To generate a Run/Debug configuration for a PHP script
Right click in the Project tool window, and select from the context menu (make sure to pick the item marked with ). Alternatively, open the script in the editor, press Shift+Alt+F9, and select the script to be debugged.
The IDE will launch the script with the debugger enabled, and open the Debug Tool Window.
Launch the Debugger
To launch the debugger
Do any of the following:
Click on the PhpStorm toolbar.
Selectfrom the main menu.
Starting a debugging session from the command line
Before you start a debugging session with PhpStorm when running CLI scripts, make sure that any of the following requirements is met:
remote_autostartoption is enabled.
XDEBUG_CONFIGenvironment variable exists.
Listen for incoming debugger connections
In PhpStorm, enable listening to incoming debug connections by either clicking on the toolbar or selecting debug tool window automatically. Before launching the script, make sure that either a breakpoint is set or the Break at first line in PHP scripts option is enabled on the Debug page of the Settings/Preferences dialog (Ctrl+Alt+S).. This will ensure PhpStorm reacts when a debugging session is started and opens the
Start the script with debugger options
Since we'll be starting the script from the command line, we will have to make sure it is started with the required settings to enable the debugger.
To start the script with Xdebug
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 parameter. Alternatively, you can set an environment variable so that you don't need to provide the
-d parameters every time.
To start the script with debugging using PHP command line switches
Set an environment variable that would tell XDebug to connect to IDE:
idekeyshould have a random value.
Launch PHP with the following command-line options:
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 may use
127.0.0.1with Vagrant (see related SO question).
To start the script with debugging using an environment variable
Set an environment variable that configures Xdebug:
set XDEBUG_CONFIG="remote_enable=1 remote_mode=req remote_port=9000 remote_host=127.0.0.1 remote_connect_back=0"
export XDEBUG_CONFIG="remote_enable=1 remote_mode=req remote_port=9000 remote_host=127.0.0.1 remote_connect_back=0"
Start the script normally:
Optionally, we can use Xdebug's remote_autostart setting to always start a debugging session for every script that is run.
To start the script with Zend Debugger
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.
To start the script with debugging
Start the script normally:
Optionally, to tell PhpStorm which path mapping configuration should be used for a connection from a certain machine, the value of the
PHP_IDE_CONFIG environment variable should be set to
SomeName is the name of the server configured on the of the Settings/Preferences dialog.
If this environment variable is not set - you'll be prompted to specify path mappings manually once IDE detects an incoming XDebug connection.
Once the script is started, PhpStorm will open the Debug Tool Window and break at the first breakpoint that was set in the script. Next, we can continue debugging our PHP CLI script using PhpStorm as described in Examining a Suspended Program.
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.