Sunday, October 28, 2007

Getting Breakpoints to work in Eclipse PDT using Zend Debugger

November 18th, 2007 UPDATE: Please see the section at the bottom of this post for an update!

I've recently been fooling around with PHP.

At work we have a Drupal-based web site, and I figured it was time to get a better mental-grasp around PHP. After looking through a whitepaper from IBM titled Using open source software to design, develop, and deploy a collaborative Web site I decided I needed to get myself a development environment setup in which I could work with Drupal 'under-the-hood'.

IBM's whitepaper was written in various pieces over the course of about a years time. One of the sections discusses setting up Eclipse with different plugins that facilitate PHP development. In a later section they mention the PHP Development Tools (PDT) - a more comprehensive set of PHP development and debugging tools for Eclipse. Lucky for me, they now have a PDT all-in-one Eclipse package that makes setup even easier. (Get the package from here.) After downloading and installing it, and getting a feel for the whole thing (wow, Eclipse is complicated at first,) I got down to the brass-tacks and tried debugging.

Before I go on, here's a little more information about my development environment:
  • OS: Window XP SP2
  • Development Environment:
    • Eclipse : PDT
    • PHP 5.2.4
    • MySQL 5.Something
  • Web server: Apache
PHP, MySQL and Apache are all from the Apache Friend's XAMPP package.

I followed the instructions on the PDT Wiki for instructions on how to Install the Zend Debugger for Eclipse.

Just for reference, in the screenshot above, you'll notice my "Dummy Debugger Test Server" configuration. Here's a screenshot of the specific details of that config:

After getting everything setup, I could get the debugger to debug any PHP-based web page -- so long as I had the "Break at First Line" debugging option set. I could start the debugger and at the first line of PHP code, the debugger would 'catch', and allow me to step through my code. Everything worked as expected - variables and their values were visible in the Variables dialog, I could step into and out of various functions. Unfortunately, if I set breakpoints anywhere, they would never 'hit', the debugger wouldn't halt the PHP execution on the specified breakpoints. It would zip right past them as though they never existed.

Naturally I hit-up my good friend Google for answers. I found a number of people having the same problem as myself. I found instances of people having this problem all the way back in January of 2007. I also found instances of people having this problem as recently as October of 2007! Every single time I found someone saying they had the problem, nobody ever had an answer for them!

Finally, finally, I was able to find this somewhat cryptic post on how someone fixed the problem:

Not sure if this helps, but I ran into the same problem myself. I found out that it was that the plugin expects the project root to be the http root.

My project structure had the http root as a subfolder of the project root.

If the http root isn't the same point as the project root, then the plugin can't correctly inform the debugger which file the breakpoint is in.

I ended up hacking the source to make the plugin work at a subfolder level.

Problem was, he stated that he hacked the source of the plugin to 'make the fix'. Not exactly what I was hoping to do. I figured I was approaching yet another dead end, but something about him stating that the plugin was simply confused about expecting your Eclipse project's root to be the web server's root gave me an idea: Move my content to the virtual host's root directory.

I tried moving my project's files all into the root folder of the web server (just dummy.php in this case.) I modified my "Dummy Debugger Test Server" configuration as shown in this screenshot:

I made sure that "Break at First Line" was unchecked/disabled, and fire up the debugger. It worked. It finally worked. After all that trouble it freakin' worked.

Has anyone else had this much trouble? Has anyone been able to get debugging to work when your debugged PHP doesn't reside in the root of your web server?

November 18th, 2007 Update:
I think I may have a better example. I've also been 'playing' around with the Symfony PHP Framework. I again ran into this breakpoints-not-working problem when trying to debug a Symfony-based project.

I'm going through the "Askeet" tutorial and have imported a project into Eclipse and had my Apache instance serving up the "/web" subfolder served up as the server's document root.

Of course, this confuses the debugger plugin, because, again, the debugger is assuming that the Eclipse project-root corresponds directly to the web server's root directory, which it's not. This is the situation:

The arrow titled "Assumed" is what the debugger is wrongly assuming. To fix the problem, you have to configure your web server to match that assumption.

So, I modified the virtual host's DocumentRoot to point to the Askeet project's root folder, even though there is no index.html or index.php to be served from there. I had to also modify the "/sf" alias to handle "/web/sf". (If you're using Symfony, you should know what I'm talking about.) So, now instead of going to http://localhost, I have to go to http://localhost/web/. But since this is strictly for development purposes, it's not a big deal. Oh, and I had to make a slight modification to the debugging profile in Eclipse to match the new /web/index.php URL. Again, not a big deal.

I hope this update cleared any confusion...