How to Setup XDebug with PHPStorm

The first time I tried to use PHPStorm with XDebug was - in all honesty - a total nightmare. It didn't help that I was working on a project with a looming deadline, and no matter what I tried, nothing seemed to work.

Now, that was back in the Good Old Days (tm) and things have certainly moved on quite a bit since then.

One of the most helpful tools that JetBrains now offer is the XDebug bookmarklets generator. Right away, this will make configuring the interaction between your browser and your IDE a heck of a lot easier.

When working with Symfony, checking whether XDebug is installed and enabled is as simple as looking at your Web Debug Toolbar. Inside your app_dev.php (dev) environment, mouse of the PHP icon on the toolbar and you'll see a red or green XDebug badge. If it's green, you're good to go. If it's red, you will need to install and enabled XDebug.

If you're running a Debian / Ubuntu based Linux system, installing XDebug is pretty easy.

sudo apt-get install php5-xdebug

And then, restart your web server, e.g.

sudo service apache2 restart

After that, if you refresh the app_dev.php page in your browser and mouse over the PHP logo, you should see the XDebug badge is now a friendly shade of green.

Alas, that's not the end of our config.

The next thing you'll need to do is modify your XDebug config file. Now, where this will be located differs depending on your system. Redhat / CentOS do seem to put things in sufficiently different places to the Ubuntu / Debian equivalents. Google is your friend.

In our case, we can edit the file with vi:

sudo vi /etc/php5/apache2/conf.d/20-xdebug.ini

And the reason I say that it doesn't matter which we edit (apache2 or cli) in the video is because these folders are symlinked so as not to duplicate the config files.

Regardless of where your config file lies, you will need to add in the following:

* existing stuff here*
xdebug.remote_enable=1
xdebug.remote_port=9000
xdebug.idekey=PHPSTORM123
xdebug.remote_connect_back=1

Save and exit, then restart Apache (or whatever web server you're running - and if it is nginx, be careful with the ports as 9000 may conflict)

sudo service apache2 restart

Now that your config is all good, be sure to drag and drop the XDebug bookmarklets onto your browser toolbar for handy use.

Once that's done, head inside PHPStorm and open up the Run / Debug Configurations menu page. (03:50 onwards in the video, if unsure).

Add in a PHP Remote Debug profile.

You'll likely need to add in a new server, so click the Plus symbol, and then give your server a name (I tend to use the IP address of the server here, but feel free to use whatever), and make sure you match the Port number to the one you set up in your XDebug config - 9000 in our case.

Lastly, be sure to add in the Absolute Path to your project. This is essentially the path on the remote server that maps to your local project files. In our case this is:

/var/www/html/codeception_is_awesome.dev

Then you can validate your config. This bit never works for me, but it seems to have no negative effects other than that.

Be sure to add in your IDE Key. If you followed my example, that would be PHPSTORM123. I change this from the defaults on the off chance that you somehow put this into production.

All that's left now is to enable Debugging inside your IDE by clicking the little bug icon and adding a breakpoint, then starting the debugger inside your browser via the bookmarklet, refreshing the page and you should be dropped into your IDE at the point when you hit the breakpoint.

One thing to be aware of - debugging Symfony can be a little messy. There's the entire Framework to get in the way of your code, so if you come unstuck, be sure to check out the How to Optimize your Development Environment for Debugging cookbook article which goes some way to reducing that.

This method works on none Symfony projects also.