If your'e going to debug Drupal, or any PHP project, you're going to need tools. There's more than a few options to choose from. The most basic would be instrumenting code with print() or echo() statements. While it would be serviceable, it would mean modifying core itself, and that's generally considered a Very Bad Thing. For professional development, it appears the KomodoIDE is the most popular. It's reputation is that it "just works". If I were looking into professional tools, it might be worth the $300 price tag. Given my open source, Linux using, bent, what is there?
The Eclipse project is a IBM-backed, Open Source Integrated Development Environment (IDE). It provides source file editing, syntax highlighting, code completion, project storage, and it's extendable through plugins. Eclipse was born out the myrad of IDEs and GUI tools that IBM provided to develop and administer their various middleware projects. IBM no longer wanted to maintain all these separate tools, and set out to create One IDE to Rule Them.
Instead of one generic interface, Perspectives provide the appropriate views, editors, and functionality suited to the project at hand. This can be as simple as different programming languages, or a separate development and administration perspectives for the same enterprise product (such as WebSphere Message Broker). While Perspectives are Eclipse's greatest feature, they also cause huge amounts of confusion for new users. IMHO, Eclipse's bad usability reputation is due to a disconnect between an enterprise IT mentality from which Eclipse hails, and the expectations of independent developers that are expecting a domain specific IDE.
This is not to say that Eclipse doesn't have problems. It's a hulking beast of a program. It takes some time to load. And yes, configuration can be weird for some users (I have sadly noted many of those users are also particularly fond of a fruity brand of consumer tech). I'm actually quite comfortable with Eclipse thanks to my background in Middleware. It runs on multiple platforms, and I can easily acquire plugins for other languages.
PHP Developer Toolkit
One of those plugins is the PHP Developer Toolkit (PDT). It extends Eclipse's functionality, providing the IDE the necessary know how to work with PHP code. This includes syntax highlighting and code completion. It's the bit that makes plain Ecplise into a PHP IDE.
There are two options to install PDT into Eclipse. You can download a pre-bundled tarball of Eclipse with PDT already installed. This is easiest for many users. The other option is install a base copy of Eclipse and then use Help -> Install New Software to install all the required modules. I prefer this method on Linux platforms as it allows Eclipse to be installed with the Linux distro's native package manager.
Some users will be shocked at just how many clicks this requires, and it is a lot. You have to select the modules, agree to the license agreement for each module, wait for it to download, then restart the IDE. As enterprise software goes, this is a cakewalk. The record holder for installation time I've worked with was three weeks. And no, you don't want to know what the installer looked like and how many clicks it requires.
One component that PDT does not supply, is a debugger. I've never used a debugger with PHP before. Before I started using Drupal -- when I did most of my PHP coding -- they didn't even have debuggers. I needed something that was relatively easy to install, something current, and something open source. XDebug hit the sweet spot.
XDebug also has a bad rap among Drupal developers. It's often thought of too complicated to install, too fritzy, and does not work consistently.
I had XDebug working in 10 minutes flat.
How did I pull this off? XDebug only provides binaries for Windows systems, and source for all other platforms. Given the predominance of fruity computers in Drupal development, it's no surprise to me that attempting to build XDebug from source is a huge hurdle. (Besides, if you can afford one of their systems, why not plunk down $300 for the KomodoIDE?)
Being an FLOSS wackaloon, I use Linux. XDebug doesn't provide binary builds for Linux either, but that's not the end of the story. Many distros of Linux will provide a build of XDebug in their package manager. The distro I'm currently fond of is Arch, a rolling-release distro that does not even provide a graphical installer. Arch provides a build of XDebug in the Arch User Repository (AUR). I needed to only run the AUR wrapper script to install XDebug.
Getting XDebug and Eclipse PDT to Play Nice
XDebug is actually an Apache 2 module. You configure it as you would any other Apache module. When initiating a debug session, a $_GET variable is passed containing the debug session key. The PDT knows how to issue that key, so all you need to do is configure Eclipse to use XDebug.
First of all, you will need to configure Apache to use XDebug correctly. When I tried this, it turned out that AUR did all the work for me. However, you can hit up this page for a solid reference for getting XDebug up on Arch. Once configured, restart Apache.
- Go to Window -> Preferences to open the Preference window.
- Expand the tree view on the left and select PHP -> Debug.
- Select the PHP Debugger as XDebug. If this option is not available, click the Configure link to the right of the pop-up menu and add the configuration. The default port of XDebug is 9000.
- Click the PHP Servers link. Add your server (localhost is OK!). Select your new server in the Servers popup menu.
- Click the PHP Executables link. Add a new PHP executable configuration with the following options:
- Set the Executable Path to /usr/bin/php. This is the default for Arch. Your distro may vary.
- Set the PHP ini file to /etc/php/php.ini. This is the default for Arch.
- Select the SAPI type to CLI.
- Select the PHP Debugger as XDebug.
- Return to the Preferences window. Click OK.
Initiating a Debug Session
I admit this one is more fussy than I had wanted, mostly because for this project I'm not developing any code. Eclipse PDT assumes that you have created a project with code to debug. When initiating a debug session, the expected workflow is to open the source file you intend to debug. Then select Run -> Debug As -> PHP Web Server. This switches Eclipse to the PHP Debug Perspective, and loads the file path you entered in step 4 above, passing the all important debug session key.
Currently, I have a project set up for a patch to Organic Groups. When I invoke Debug as PHP Web Server, it attempts to load the project file path, og-rules-patch/og.module, on the webserver, http://localhost/og-rules-patch/og.module. This would obivously result in a 404, but that's all that we need to start exploring!
Once we drop into the debugger, we can start stepping through Drupal code. Our first stop is how Drupal initializes -- drupal_bootstrap(). That's where we'll pick up next time.