Debug CLI scripts with PhpStorm and XDebug

While developing the WP Browser package I’ve often ran into the need to debug Codeception modules and this means PHP scripts running and living in a command line context.
I use PhpStorm to debug as setting up a debug environment is a breeze in most of the cases. CLI scripts can be debugged as well with a less user-friendly set up.

Homebrew my PHP

To make any setting reversible I’ve installed Homebrew and skipped the OS-embedded version of PHP altogether to run, in its place, an Homebrew managed and provided one.

brew install php53 php53-intl php53-xdebug

I’m installing version 5.3 of PHP (the minimum requirement for Codeception), internationalization functions and XDebug.
Homebrew will take care of setting it all up and running the php --version command will result in the comforting prompt
php --version terminal command  output

Enabling XDebug for the command line

While testing web applications I can use the handy Chrome Xdebug helper extension or resort to JetBRAINS provided bookmarklets to enable and disable debugging but will be on my own when it comes to the command line.
After some research I’ve set with the simple solution of creating aliases to enable and disable XDebug with a quick command like

alias xon="export XDEBUG_CONFIG=\"profiler_enable=1\""
alias xoff="export XDEBUG_CONFIG=\"profiler_enable=0\""

An example workflow

In a totally unrelated example I might have problems with my afore-mentioned Codeception add-on and willing to debug the flow of the module building phase I will set PhpStorm to listen for debug connections
PhpStorm menu to enable listening for debug connections
will enable XDebug profiling and will then run the script to debug until satisfied

codecept build

Many debug sessions later I will turn XDebug profiling off


One thought on “Debug CLI scripts with PhpStorm and XDebug

I appreciate your input