Quick Xdebug Troubleshooting

If you’re like me, you would have to find a new vocation if you didn’t have a debugger in your IDE. I don’t know how anyone writes or troubleshoots code without being able to stop at breakpoints to check the status of variables or to step through the flow of a complex process.

Configuring an IDE like PhpStorm for Xdebug can be somewhat perplexing. Tutorials abound on how to get Xdebug working. This post is not an attempt to churn out yet another set of instructions for setting up Xdebug, but to provide a quick sanity check in case you have everything set up and it’s still not working.

My Xdebug Config

Xdebug requires that some settings be added in the [Xdebug] section of your php.ini file (which varies depending on your local environment setup - i.e. MAMP, VM, etc). When troubleshooting your dev environment setups, it’s often helpful to compare your configuration with a configuration known to work for someone else. Here’s a snapshot of the Xdebug settings in my local php.ini:

[Xdebug]
# Depending on your PHP configuration, after downloading/installing Xdebug, note the path to your xdebug.so. The Xdebug.org site has a handy utility to help you install xdebug - https://xdebug.org/wizard.php.
zend_extension="<path to where xdebug.so lives>/xdebug.so"
xdebug.remote_autostart=1
# The remote host will depend on your local setup. If you have ‘localhost’ assigned here and things aren’t working, try ‘127.0.0.1’. This will also be different if you’re working inside a VM (i.e. 10.0.2.2 see http://pietervogelaar.nl/php-xdebug-netbeans-vagrant).
xdebug.remote_host="127.0.0.1"
xdebug.scream=0
xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_connect_back=1
# The port for Xdebug to listen to (default port is 9000).
xdebug.remote_port=9000
xdebug.profiler_enable=1
xdebug.profiler_enable_trigger=1
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.cli_color=1
xdebug.show_local_vars=1
xdebug.idekey=PHPSTORM
xdebug.remote_log="<path to where you want your log to live>/xdebug.log"

Common Gotchas

When I was helping a fellow colleague troubleshoot his Xdebug setup, I noticed that he had his xdebug.remote_host set to localhost. When I checked my Xdebug settings, I had my xdebug.remote_host set to 127.0.0.1. When he switched his xdebug.remote_host from localhost to 127.0.0.1, voilà! He was stepping through code like the boss that he is.

Another gotcha is the xdebug.remote_port setting. Make sure the ports match between your settings and whatever you have designated in your IDE.

The IDE key in your browser extension is also worth a look. Confirm that it matches the xdebug.idekey in your active php.ini settings.

Lastly, keep in mind that Xdebug is a huge resource black hole. You may want to increase the memory_limit on your local development environment (also a setting in php.ini) to prevent out-of-memory errors while running your application locally.

Alternatively, if you have PHP and Xdebug installed via Homebrew, consider using Xdebug Toggler, a simple script that allows toggling Xdebug on/off.

If you have other ideas or recommendations or questions about Xdebug, tweet them to us @chromatichq. Happy debugging!