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:

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?

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.