Setting up Eclipse to Debug Drupal with XDebug

Every 6 months or so I take a stab at setting up line-level, breakpoint style debugging for PHP. In the past I've been able to get the debugger installed, but the lack of a decent interface to use in setting breakpoints and watches has limited the value of a debugger (one thing that I have found helpful is XDebug's profiling feature that lists all function calls in a nested format along with performance timing). The recent announcement of a new XDebug client for OS X got me back on that track, and while I wasn't able to get MacGDBP working as I wanted, it did lead me to re-evaluate the newest Eclipse offering for PHP coders: PDT. PDT has come a long way, and the combination of a robust IDE, nimble 'jumpt to' shortcuts and killer debugger integration are more than I can pass up. Here's how I got everything working on a Mac OS X 10.5 box.

Much of what follows was made possible by and incorporates instructions from these very good tutorials:

• How To Setup a Free PHP Debugger using Eclipse PDT + XDebug is for Windows users but has very detailed instructions on setting up the Eclipse environment once Apache and PDT are up and running (via the PDT Wiki)
• Xdebug: Documentation for installation instructions
• MAMP and Xdebug at my 2 cents has a link to pre-build XDebug binaries

Install MAMP with XDebug

1. In order to get the XDebug debugger working with the PHP provided my MAMP, we need to download the MAMP Full package. This is not a commercial package like MAMP Pro, but a version of the regular MAMP software package with all library files required to install XDebug and similar extensions included. The latest version as of this writing can be downloaded here, and the most current version can probably be found at the bottom of this page.
2. Once you’ve downloaded the MAMP package, copy the entire MAMP folder into your Applications folder. You can then start up the MAMP application to make sure everything is working (it should load a test page to confirm once the Apache and MySQL servers have booted).

3. Using this MAMP distribution makes installing XDebug as simple as running the command sudo /Applications/MAMP/bin/php5/bin/pecl install xdebug. Really. Once this is done just add the following lines to your php.ini file in /Applications/MAMP/conf/php5/php.ini (note that the location of the .so file is not the same as the extension files that ship with MAMP, since the XDebug version is more recent than those builds):

    zend_extension="/Applications/MAMP/bin/php5/lib/php/extensions/no-debug-non-zts-20060613/xdebug.so"
   
   
    [Xdebug]
    xdebug.remote_enable=1
    xdebug.remote_host=localhost
    xdebug.remote_port=9000
    xdebug.remote_autostart=1
    xebug.remote_handler=dbgp
   

4. Now, stopping and then starting your MAMP Apache server using the MAMP application in Applications/MAMP should give you an XDebug-enabled PHP install running on port 8888 (the MAMP default). To check that everything’s working as it should, click the “Open Start Page” button in the MAMP application window (though it should have automatically opened when you restarted Apache), then on the “phpinfo” link in the top nav of that page. Searching in this page should turn of a number of references to XDebug, including a section devoted to various XDebug variable settings.
   (screenshot)

5. See http://drupal.org/node/66187 and https://techcommons.stanford.edu/drupal-book-toc/create-local-development-installation for some tutorials on how to get Drupal setup on MAMP.

Install PDT, the Eclipse PHP Editing Environment

PDT has been “in development” for a long time, but after about a week of working with it I have to say I’m very impressed. I still prefer coding in Textmate, but since PDT has everything I need in a text editor (jump to file and jump to function keystrokes, mainly…though I can’t find out how to easily set markers for quick jumping to specific lines) and also support line-level debugging, I’m moving much of my coding to the PDT IDE environment. In addition the downloadable all-in-one distribution of Eclipse, PDT and all required Eclipse modules for PDT makes installation a real snap:

1. Download the latest version of the PDT all in one from http://downloads.zend.com/pdt/all-in-one/ then copy the “Eclipse” folder to /Applications.
2. For more information on setting up Eclipse, check the PDT documentation and wiki (the wiki is especially helpful).
3. Assuming that you’ve installed your Drupal install in /Applications/MAMP/htdocs (personally I use virtual hosts, but more on that later), you’ll need to start a new PHP project in Eclipse using the exiting code from your Drupal directory. To do this, start Eclipse then go to the Workbench view (if you get the odd startup screen when you start Eclipse). Select “New Project” from the “File” menu, then choose “PHP Project” from the nested listing in the following window. Name your project something appropriate then uncheck the “Use Default” under “Project Contents” and Browse to the folder containing the Drupal project you want to debug (or any other project, for that matter).
   (screenshot)
4. Click OK then choose “Create project in” your directory instead of the default which is to create a new folder within the folder you’ve browsed to. This will import the existing files into your project.
   (screenshot)
5. A few nifty Eclipse keystrokes for getting around: “Command-Shift-R” can be used to jump to any file in the project, just start typing the name. Once you’ve opened a file, “Command 1” can be used to jump to any function, class or global variable declaration in that file.
6. To get Eclipse to parse .module and .engine files as PHP, open the Preferences screen in Eclipse and then choose General->Content Types from the settings tree on the left of the window. Expand the “Text” tree in the “Content Types” textarea and choose “PHP Content Type” entry then click the Add button next to the “File Associations” listing twice, adding entries for “*.module” and “*.engine”.
   (screenshot)

Setting up Eclipse Debugging with MAMP

Now for the fun part.

1. Open the preferences window using “Command+,” or go to the “Eclipse” menu and choose “Preferences”.
   (screenshot)
2. Set up a new PHP server: expand the the “PHP” item in the preferences tree in the left of the Preferences window, then select the “PHP Servers” option. Click the “New” button to add a new server definition, name it as you wish (I went with the boring “MAMP Localhost Port 8888”) and specify the base URL for the local server (MAMP default will be “http://localhost:8888”). Click “Next”.
   (screenshot)
3. Map the root of the server to the root of the project you are debugging: click the “Add” button to add a new path mapping, then enter “/” as the path on the server then click the “Browse” button next to the “Path in Workspace” text box and select the project root (the top-level item with the name of your project) and click OK. Click finish to save the new server definition.
   (screenshot)
4. In order to get the benefits of Eclipse’s automatic parsing of PHP files for syntax errors, add a new PHP executable under “PHP Executables”, setting the path to /Applications/MAMP/bin/php5/bin/php if you want to use the php binaries provided with MAMP.
5. Set up your debugging session: choose “Open Debug Dialog” from the “Run” menu, choose “PHP Web Page” from the listing on the left and then click the “New Page” icon to add a new debug configuration (or double-cick “Php Web Page”).
   (screenshot)
6. Choose “Xdebug” as the “Server Debugger”
   (screenshot)
7. Choose the new server configuration you created in step 2 as the “PHP Server”.
   (screenshot)
8. For “File” click “Browse” and select the “index.php” file under the project you are debugging (this is true for all Drupal installs, other apps will probably be similar by YMMV).
   (screenshot)
9. Under the “Common” tab check the checkbox next to the “Debug” icon in the “Display in Favorites Menu” setting area, then click “Apply” to save and “Close” to close the dialog.
10. Now, clicking on the arrow next to the “Bug” toolbar icon will bring down a drop-down menu with one of the options being the new debugging profile you have created. To start a debug session, select that item.
    (screenshot)
11. You’ll need to also choose the “PHP Debug” perspective using the perspective chooser in the upper right corner of the workspace.
    (screenshot)
12. Once your there you’ll have controls to continue playing through the code, or to move step-by step either diving into each successive function call (“stepping in”) or stepping over function calls onto the next line in a given script (“stepping over”). To set a breakpoint while editing or executing, double click in the light-blue gutter region to the left of the line numbers.(screenshot)

Up next: using PDT, Eclipse and XDebug to debug and reverse engineer Drupal code!