If you find Xdebug useful, please consider supporting the project.

Xdebug Control

A command line tool to instruct Xdebug's step debugger to connect to the IDE or pause execution.

Installation #

A binary for Linux and Windows is available on the downloads page. You only have to download the binary, which you can then run from a command line.

Command Line Options #

The following command line options are available:

-h Show this help
-p value  Specify the PID (Process ID) of the PHP script to operate on. This is needed when there are multiple PHP scripts running at the same time.
-v Show version number and exit
-x Show protocol XML. With this option enabled, the client will also show the raw XML data that the Xdebug sends back. This can be useful for debugging issues with the interaction between Xdebug, and this tool.

Usage #

Listing Processes #

To list all PHP scripts that have the control socket available, run:

./xdebugctl ps

This should output a list with all running PHP scripts:

       PID      RSS     TIME COMMAND
   1414004     1193 23596.36 /home/derick/dev/derickr-mqtt-fun/test.php (Xdebug3.5.0alpha3)
   2638744      510    10.51 /tmp/show-time.php (Xdebug3.5.0alpha4-dev)

For each running script, it shows the Process ID (PID), the current memory usage (RSS), how long the script has been running for (TIME), the script's file name (COMMAND), and the Xdebug version.

If a PHP script does not respond to the command within 100ms, then the tool will show a warning: 

       PID      RSS     TIME COMMAND
    263942 Error: No response on: @xdebug-ctrl.263942

Pausing Running Scripts #

With the pause command you can ask Xdebug's step debugger to make a debug connection to a listening IDE, or if a connection is already active, to force a breakpoint.

./xdebugctl pause

Xdebug's step debugger must be enabled through the xdebug.mode setting for this command to have any effect.

If the running script is not yet connected to an IDE, this produces: 

   2677578 IDE Connection Signalled

If the running script is connected to an IDE, but not in a "breakpoint" state, then the command forces a breakpoint, and displays: 

   2677578 Breakpoint Signalled

If there is more than one PHP script running, and you don't specify its PID, then you will get the following error (followed by the help text): 

Error: You must specify a PID with -p as there is more than one script

In this case, you must use the -p flag with the Process ID so that the tool can distinguish the different running scripts: 

./xdebugctl -p 2677578 pause