How to debug PHP CLI applications using XDebug and PHPStorm

How to debug PHP CLI applications using XDebug and PHPStorm

Problem statement

It is a very common requirement to debug a PHP CLI application while you are working on a new feature, or fixing a bug.

Statements like var_dump, print_r, etc. work, but sometimes it’s ideal to check the execution flow in detail, and view the state of the variables in the flow. PHP xdebug, to your rescue.


We’re assuming that you’ve the xdebug extension installed. If not, follow these instructions.

Let's jump in

  1. Configure PHP CLI interpreter in PHPStorm. If you haven’t done this already, you can find the steps here image.png
  2. Take note of important information such as: client_host, client_port. You can obtain their values by executing php -i | grep xdebug from your machine. Let’s say, client_host is localhost and client_port is 9003
  3. Enter the details in PHPStorm like this: image.png
  4. Start a xdebug session from the command line by executing export XDEBUG_MODE=debug XDEBUG_SESSION=1
  5. Make sure PHPStorm is listening to connections Screenshot 2022-05-25 at 5.42.52 PM.png
  6. Add a breakpoint in PHPStorm, and run the CLI app from the command line. Here are some screenshots for your reference: Screenshot 2022-05-25 at 5.49.41 PM.png

Screenshot 2022-05-25 at 5.50.59 PM.png

Screenshot 2022-05-25 at 5.51.34 PM.png

Screenshot 2022-05-25 at 5.54.20 PM.png


I hope that you are now aware of how to do the setup. Please feel free to reach out via comments in case you are facing any issues.