Drupal debugging like a pro

A Blog Post by
Drupal debugging like a pro

It is one of the most tedious and annoying parts of development, and if you can learn to do it effectively you can save yourself hours or even days of work.. and even a grey hair or two.

Effective debugging is often a neglected subject in development courses and you usually end up finding creative ways to search for pesky errors. I'll start off by covering a few debugging techniques.

1. echo() & print_r()

The echo() and print_r() PHP functions are amongst the easiest and quickest ways to check a variable on screen, and one of the first debugging techniques we learn ourselves. The problem is just that, it's old and belongs on rocks with other cave drawings from the prehistoric age.

Pros: Quick, easy to use, always available

Cons: Unstyled output, breaks submission execution flow, requires code modification, not very readable for big objects

global $user;
echo $user->name;

2. var_dump(get_defined_vars());

When sorting through echo data we naturally start looking at better ways to print these variables to screen. I often wrapped this with the die() function to stop page execution. Now this is more readable, but this method still has some drawbacks like the fact that you have to hide it for certain pages or users manually. This means more code that you have to add and potentially forget about. If you want to correlate between what is rendered and the variable that you outputted, or different fields in the variable, you have to constantly scroll up and down, and you end up loosing your place all the time.

Pros: Easy to use, quick, more readable, always available

Cons: Requires code modification, not very readable for big variables

3. dpm();

Now the next evolutionary step in the debugging process has to be some sort of print wrapper. Now the devel module has one of the best. Now add some JavaScript, and the dpm() function prints out variables in very attractive and space efficient way. Now dpm() also addresses a very important problem, and that is that the other debugging methods break process execution. If you want to submit a form and want to see the variable data and rendered page you can't. The dpm() function however allows you to go through this process and it will print the variable on the first rendered page it gets.

Pros: Quick, easy to use, space efficient, doesn't break execution flow, very readable

Cons: Requires the devel module, requires code modification

global $user;
dpm ($user);

4. XDebug

Now debugging just got serious. In short, Xdebug is the super sayan level six Swiss army knife of debugging. Xdebug allows one to add breakpoints to code and step through line for line and see how the variables a affected, what modules get called when etc. You can modify variables as you go, see a detailed call stack, step in and out of functions and much more. It is a bit of a mission to set it up initially but it's worth the effort. No code modification required and no additional modules.

There is however two problems with this approach:

  • Xdebug won't be available on many shared or managed hosting enviroments.
  • PHP IDEs that has Xdebug support could be pricy.

Finding bugs in the hidden nooks and crannies

Debugging using the above mentioned tools will help you out of the majority of cases. There is however three important debugging tips I picked up over the years.


Now if you're getting irregular output, your changes don't rerflect or your test output just doesn't print, it usually ends up being one of the many layers of cache in your Drupal setup. Now in dev enviroments I recommend switching of all forms of cache. CSS and JavaScript aggregation and caching can be annoying but easily checked with a tool like Firebug. If your used to blindly tapping Ctrl + F5 to clear cache, It might be worth your while looking at a tool like Web Developer extension for your browser with "Disable Cache" ticked. The Advanced CSS/JS Aggregation module solves a lot of bundling, performance and caching issues, but flush it regularly to make sure the latest page load is nice and fresh.

More aggressive caching techniques like memcache, authcache, Varnish etc. should also be checked and flushed if it's might be acting up.


Drupal's hook system is pretty nifty. It allows you to easily extend Drupal with custom modules without hacking the core to get the desired output. Once in a while you implement a hook function and you find that another module has beaten you to the punch and set a certain variable or called a certain function. Now if you need to find out what evil module is causing you the pain you can add a few lines in the module_invoke_all() function located in includes/module.inc.

function module_invoke_all() {
  $args = func_get_args();
  $hook = $args[0];
  $return = array();
  foreach (module_implements($hook) as $module) {
    $function = $module . '_' . $hook;
    $result = call_user_func_array($function, $args);
    if (isset($result) && is_array($result)) {
      $return = array_merge_recursive($return, $result);
    else if (isset($result)) {
      $return[] = $result;

  // Add your debug code here.
  // e.g. if ($hook == 'init') { dpm($module);

  return $return;

Now you can check a a particular hook and see exactly what module caused a change. Majority of the time you'll be able to fix the problem by changing up some module weights. This will allow you to fire your module before another module, and can be easily adjusted by adding the Util module.

GOOGLE and Drupal.org

This is without a doubt the one of my most important tools in my toolbox. If you get an error and you don't know where it's coming from ask uncle Google. Drupal module issue queues has some information on your module specific bugs.

This is just a basic rundown on Drupal debugging. Hope this post helps you to do some code fumigation and keep that little bugs at bay.

Created: Wed, 23/05/2012 - 17:13