Debugging PHP Command Line (with PHP Storm & XDebug)

At PHP North West I had huge difficulties configuring Xdebug and both my PHP and PHP Storm so they play nice in a CLI environment. So here, for others and almost certainly my future self, is how to do it.

Note: This is on a MacBook Pro on OSX 10.9.6 running PHP 5.6 


Firstly, you need to check Xdebug is configured for remote debugging and has an IDE key set. In my case, because I’m running PHP-FPM on port 9000 I also had to change the default port that Xdebug sends data to. I ended up with something like:

xdebug.remote_enable = 1
xdebug.idekey = "PhpStorm1"
xdebug.remote_autostart = 1
xdebug.remote_connect_back = 1
xdebug.remote_port = 9998

Running a php -i | grep xdebug then shows that these settings have taken and are set.

PHP Storm

Next, we need to setup a debugging environment in PHP Storm, I have no idea if there is a quicker/better way to do this, but here are the steps I took:

  • Click the arrow next to the debug environments list (it may be empty and just be an arrow):

Debug Tool Bar

  • Select “Edit Configurations…”
  • Click the “+” to add a new configuration and then select “PHP Remote Debug”:

  • Give this config a name, and select which “Server” this debug profile uses, if you don’t have a “Server” configured, click “…” and add one – give it a name and make sure it’s picked as running Xdebug:

Add server screen

  • Make sure this new “Server” is selected, and make sure that the IDE Key is the same as the one you set in the Xdebug config above

In order to tell PHP Storm to listen for debugging using the settings we specified, first click the “Debug” icon (second from left bug), then click the telephone “listen” button (forth from left), the telephone should turn green to say it’s listening and you should see the debug pane appear below.

Debug Tool Bar

We’re nearly there now!

Make sure you’ve got a break point set on your code somewhere (or you have auto stop at first line enabled), we just need to tell the CLI to use the debugger. To do this, we just export an environment variable using the IDE key we set above (in my example PhpStorm1).

export XDEBUG_CONFIG="idekey=PhpStorm1"

Now you can just run your cli file as normal, and PHPStorm will stop at the breakpoint allowing you to step debug. Make sure you unset this variable again when you want to stop debugging or you might get unpredictable results (I forgot and my IDE was waiting for debugging on a composer update once).



Note – when I just came to configure this myself, I just realised I was running Xdebug on an atypical port (9998) – this meant I needed to configure PhpStorm to tell it that. To do so I simply found the Xdebug config
by using CMD+SHIFT+A (search anywhere) and then typing Xdebug – the port setting is on the resulting preference screen.

Huge apologies for the delay, I completely forgot to finish this post until I needed to configure my MacBook again today and had to figure the last 20% out again. I know some people were waiting for this, so I can only say “sorry!”.

5 thoughts on “Debugging PHP Command Line (with PHP Storm & XDebug)

  1. Gary, you just saved me from figuring this out by myself… just when I needed to debug a cron-script you publish about debugging on CLI. You must have received my brain waves somewhere in the future, came back and did me a big favor.

    Thanks for this :+1:

  2. Hey Gary,

    You helped me with this today at the True North PHP conference, so I just wanted to add a few thoughts and experiences that we noticed together in case anyone else runs into the same problems.

    Re-reading the post above you do cover what was happening, but in a different way. Where you say that you need to unset the exported shell value (XDEBUG_CONFIG) you can also just uncheck the two values in the Xdebug preferences pane that force php to stop on the first line. See this Stack Overflow answer to see a picture:

    Also, in my specific case we noted that CMD+Shift+A was overridden by another application that I have on my mac, and you can also get to the same menu by pressing CMD+, and then typing Xdebug, without ever having to use your mouse 🙂

    Thanks again for the help, Gary!

  3. Coming from a .NET environment where debugging is built into Visual Studio and just works, and the pain it was to setup the debugger in PHPStorm and PHP, I think it may be the number one feature to improve, and just make it work without complex hassle and configuration. I

  4. Thanks for the post.
    However, I just achieved it by specifying the Xdebug parameters from my php.ini, as follows:
    php -d xdebug.remote_autostart=1 -d zend_extension=”/Applications/MAMP/bin/php/php5.6.32/lib/php/extensions/no-debug-non-zts-20131226/”

    (if add -v I can see “with Xdebug v2.5.0, Copyright (c) 2002-2016, by Derick Rethans”)
    It worked for me..

Your Comments are Awesome, Please Leave Them!

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s