Debugging Drupal 6 using XDebug

After working full time with Drupal for 2 months, I really needed a decent debugging interface. I was tied up with using dsm(..) and var_dump(..) all the time!

Also, my lovely computer and Eclipse decided they didn't liked each other... 64bit and Eclipse, it's still a mystery what exactly went wrong or what exactly went right... Now this fight is all over and my love (and my computers) for Eclipse is back for good!

Working with Visual Studio 2005 before I learned to like the 'breakpoint' thing in .net environments.
In my hunt for a solution, I found an easy way to get the same effect for Drupal in Eclipse (and to make it even harder, in 64bit! - but this guide will also work for 32bit systems).

A quick summary of debugging info at wikipedia:

Debugging is, in general, a lengthy and tiresome task. The debugging skill of the programmer is probably the biggest factor in the ability to debug a problem, but the difficulty of software debugging varies greatly with the programming language used and the available tools, such as debuggers. Debuggers are software tools which enable the programmer to monitor the execution of a program, stop it, re-start it, set breakpoints, change values in memory and even, in some cases, go back in time. The term debugger can also refer to the person who is doing the debugging.

This guide will cover Debugging Drupal 5 or 6 with subdomains for PHP5 with the help of Xdebug and kCachegrind, also called a profiler!

1. Expected from reader
- a working Apache+PHP+MySQL system
- a working Eclipse PDT or PHP-eclipse
- basic knowlegde of linux commands & command line interface
- a working Ubuntu installation (or similar)

The base operating system I use is:
Linux version 2.6.24-21-generic (buildd@crested) (gcc version 4.2.3 (Ubuntu 4.2.3-2ubuntu7))
(you can check yours by using cat /proc/version)

2. Install xdebug + kCachegrind
Thanks to the magnificent website of devolio, a huge part of the installation is already covered.

Source: http://www.devolio.com/blog/archives/226-How-to-install-...
From the blog :

This profiler will break down your code and determine where your bottlenecks, or slow downs are to ease optimization. Combined with a program to handle cachegrind files, you can benchmark and optimize your scripts quickly and effectively.
We assume you already have Apache and PHP5 working on this system. We will be installing the latest version of Xdebug via PECL (PHP Extension Community Library.) Let's get right into it...

I assume you got through that part, and that you have xDebug and kCachegrind installed and are able to open up the files that were saved in your cachegrind directory (by default, this is the /tmp directory). The kCachegrind application should be available in your computer's application menu.

3. Eclipse Arguments and Memory Problems
To avoid having memory errors whenever we want to debug, we disable the validation and set some arguments when we start Eclipse.

In my case I have a shortcut to Eclipse with the following arguments:

/opt/ganymede/eclipse -vmargs -Xms40m -Xmx512m -XX:PermSize=64M -XX:MaxPermSize=128M

(Java heap size is the amount of memory assigned to your program.)

My version of Eclipse is 3.4.1

4. Shorten Validation Time
In Eclipse go to :

I disabled the validation when building the project since everytime we want to debug, Eclipse was validating the whole project. And since Drupal is not so small, this was a step I wanted to skip.
Nothing prevents you to leave these settings as they are.

IMPORTANT: This validation is not available in every Eclipse version.

5. Setting up Eclipse Debug Environment

Add the following to your php.ini (to enable the debugging connectivity between the PHP parser and Eclipse):

... and restart your Apache server:
sudo /etc/init.d/apache2 restart
(You have to restart: simply reloading doesn't apply the changes you made above.)

6. Configuring Xdebug in Eclipse
Since we are working with subdomains we need to tell Eclipse that every website is a remote 'PHP server'. Also, if you don't have this kind of structure I suppose this method works. It's a good way to seperate your projects from each other and to test in real life situations.

Go to:
window > preferences > PHP > debug

Select

- PHP Debugger: Xdebug
(if you don't have this -> start over and make sure xdebug is enabled and configured)

- Server: Click on PHP Servers
For every website we have in Eclipse we make a PHP Server

Fill in these 2 fields:
- Name: 'Your Project Name'
- URL: Your subdomain or url where the project can be accessed (ex.: http://localhost.drupal6 )

7. Set Eclipse PHP Executable
In order to let Eclipse use the the right system we configure Eclipse to use our binaries and our debugger.

Go to:
window > preferences > PHP > PHP Executables
- Name: 'PHP with Xdebug'
- Executable Path: '/usr/bin/php5'
you can find your path with which php5
- php.ini: '/etc/php5/apache2/php.ini'
don't just copy, verify!
- PHP Debugger: XDebug

8. XDebug has it's limits...
Since Xdebug can only work with 1 session at a time we need to tell Eclipse this restriction. (I'm not sure if this is still the case but I prefer certainty above unstable systems.)

Go to:
window > preferences > PHP > Debug > workbench options

- Allow multiple debug sessions: 'Never'

9. Some final steps...
Make sure you loaded your project in Eclipse (doesn't matter if you have more directories beneath it)

Go to:
run > Debug Configurations > PHP Web Page
or
run > Open Debug Dialog > PHP Web Page

- Click right on 'PHP Web Page' and click 'New'
- Select your new PHP Server (remember step 6? 'Your Project Name')
- Click Browse and select your Drupal Project index.php
- Check off Auto Generate

Go to:
run > Debug Configurations > PHP Web Page > Advanced
or
run > Open Debug Dialog > PHP Web Page > Advanced

- Check: 'Open in Browser'
- Start Debug From: "http://yoururl/index.php"
eg.: http://localhost.drupal6/index.php

10. Test our configuration!
Add some breakpoints to your code, for example to check if this works, add a breakpoint in index.php.

Go to:
run > Debug Configurations > Your Project
or
run > Open Debug Dialog > Your Project
- Click Debug and have fun debugging!

Next time we will handle the kCacheGrind and what you can do with it!