in Debug, PHP

XDebug and PHP setup for Mac OSX

Debugging PHP it shouldn’t be painful. XDebug it’s a fantastic PHP extension that provide debugging capabilities. The setup procedure it is easy and it already comes ready to go on XAMP and WAMP.

Let’s start for the mistake when someone try to “debug” a code for the first time. When you are digging into unknown behavior in your code you are running web server while you edit your code and press F5 compulsively. Add a die there, var_dump there and see if there is what you expect until you found something unexpected and start following that clue again.

After a few try’s you realize that it should be a better way to do that, and remember how you debug your Java App long time ago that you just add the breakpoint and press the debug icon and it works. You just had a debugger interface and you can dig in or step over on each method of your code. So you just follow the same pattern press the debug button of your IDE (PhpStorm in my case) and it shows a dialog asking for which script you should launch. However you don’t know which script to choose there, maybe you add the front controller (if there is one) and nothing works as expected and you need to fix that ASAP so you just stop researching and keep adding var_dump’s. Your mistake was trying to debug an script the front controller instead of your running app.

How do I debug my app?

In order to debug your running app you have to setup PHP XDebug, your browser and your Debugger (currently I’m using PhpStorm).  When your browser make a request to your app with the X-DEBUG HTTP Header it triggers an internal PHP connection to your IDE/Debugger and delegate the control of the runtime to your IDE/Debugger.

XDebug and PHP setup for Mac OSX

If you are using a Mac OS X you should install PEAR PECL before xdebug.

If you have not installed PEAR PECL you should follow this tutorial: Install PEAR and PECL on Mac OS X. After installing PEAR PECL you can install xdebug with a simple command.

$ sudo pecl install xdebug

With XDebug installed, you have to config it to connect to your debugger.

Check your php ini file location(s):

$ php --ini
Configuration File (php.ini) Path: /usr/local/etc/php/5.5
Loaded Configuration File:         /usr/local/etc/php/5.5/php.ini
Scan for additional .ini files in: /usr/local/etc/php/5.5/conf.d
Additional .ini files parsed:      /usr/local/etc/php/5.5/conf.d/ext-mcrypt.ini

Create the file /usr/local/etc/php/5.5/conf.d/xdebug.ini with the following content


Last step is to install some helper to remotely enable xdebug like Google Chroom Plugin.

Now all your setup it is ready, to debug your app you just need to enable the debugger listener and set a breakpoint, visit your site and finally setup the browser helper to trigger the debugger. Then your app will automatically connect to your debugger.

If you like this how-to you may be interested on: How to XDebug PHP on production or a remote application.

Please comment and share.


Write a Comment



  • How to XDebug PHP on production or a remote application - Albert Sola

    […] You also may be interested on How to setup XDebug on OSX. […]