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 

Xdebug

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]
zend_extension="/usr/local/Cellar/php56-xdebug/2.2.5/xdebug.so"
xdebug.remote_enable = 1
xdebug.idekey = "PhpStorm1"
xdebug.remote_autostart = 1
xdebug.remote_connect_back = 1
xdebug.remote_port = 9998
xdebug.remote_handler=dbgp
xdebug.remote_host=localhost

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):

• 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:

• 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.

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).

unset XDEBUG_CONFIG

Edit

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!”.