Getting XDebug working with Eclipse PDT on OS X using Macports

Having finally decided to upgrade from Leopard to Snow Leopard, I was faced with the slightly annoying task of having to upgrade Macports and rebuild my entire development environment. Thankfully, some other dude already figured out how to do that, so I was spared some degree of agony on that front. A warning though: if you do need to follow those instructions, don’t be lazy and just rename or delete your /opt/local folder - you really do need to check all those other locations and remove Macports completely.

Once the fresh Macports installation was complete and I had finished tweaking some file permissions to get Apache, MySQL and PHP working correctly, I decided I should finally try and get XDebug working. I had tried in the past and had managed to get it working with local scripts but not with Apache, which is what I really needed.

If you Google this problem you will, no doubt, find a ton of articles that show the precise configuration details (ini settings etc) required to set up Zend Debugger or XDebug with Eclipse PDT. However, if you don’t know which one of those you are installing then it can all get a bit confusing.

The most important point to note is that Zend Debugger and XDebug are two different debugging solutions that work in an almost identical way. You only need one or the other. And if you use XDebug on the back-end (Apache), then you need to configure XDebug on the client (Eclipse). You shouldn’t (can’t?) mix and match them. I chose to go with XDebug, mainly because it is installable using Macports:

sudo port install php5-xdebug

It is important to understand that the line above installs the XDebug module for Apache. It has nothing to do with the debugging client. The XDebug docs page will walk you through the process of checking your XDebug installation (checking the output of phpinfo() etc) to ensure that the Apache side of things is set up OK.

If you’re using Macports, the XDebug module is loaded by a separate ini file, which, according to the comments at the top of the file, you are discouraged from editing, as that file may be overwritten if you upgrade XDebug at a later stage using Macports.

Therefore, if you are using Macports, it is best to put all of the other xdebug configuration directives in /opt/local/etc/php5/php.ini. The only directives that I needed to add to my php.ini file in order to get web debugging working correctly (from a server-side perspective) were:


The next thing you’ll need to do is set up Eclipse PDT. There are numerous articles on how to do this. I found this one fairly informative, although this devzone article looks a little more up-to-date.

One semi-obvious thing to do is ensure that you have "XDebug" selected as your default debugger within Ecipse, NOT Zend Debugger.

If you are working with the Zend Framework MVC (or, indeed, any application that has files located at some place other than the Eclipse project root), you will probably encounter the same problem that I did, which was that of breakpoints only working at the very first line of execution and nowhere else. The key to solving the problem exists in this article. Basically, in order for Eclipse to be able to find the source code so that breakpoints work anywhere in the code, you need to configure the "PHP Server" on the Debug Configuration page correctly. Specifically, in the "Path Mapping" section of the server configuration, you need to make sure that the "Path on server" is set to the folder where index.php resides and that the "Local path", even if you are configuring it relative to the Eclipse workspace folder, includes the relative path to where index.php resides. Once you’ve got that right, you should be well on your way to achieving server-side PHP debugging nirvana!

Yet Another Programming Blog

Where James Gordon rambles about PHP and web development in general.

Find me on Twitter Find me on Stack Exchange Find me on Github Subscribe