Debugging Drupal 7 development

There are a lot of ways to debug your Drupal code while developing or when it’s running on production. In this blog post I’ll give an overview of all the tools I’ve been using the past years, going from some simple Drupal or PHP commands to external web services.

1. Drupal and PHP commands

The Drupal devel module

The Drupal devel module is basically the first Drupal module you install when you are developing a new site. You generally do NOT wish to enable this on a staging or production site as it’s quite some overhead and might expose backend information to your visitors.

The devel module has all kind of logging and extra debug information:

  • A query log at the bottom of each page
  • Xhprof integration (see later in this blog post)
  • Execution time and memory usage stats per page
  • An extra tab on every node and term page with debug output of the current object (which is an dpm($entity))

It has a big set of PHP functions you can use in your own code to debug things. Check this demo page for an overview and examples.

It also has support for using FireBug console logging if you prefer to have your logs completely outside your document’s html code.

Besides showing debug information, there is also a sub-module to generate content: devel generate. This is something people always forget during development: make sure the amount of content in your development environment reflects the later production amount! This module even generates dummy images, so your content can look pretty live-like.

dpm (debug_backtrace())

This is also available in the devel module as the function ddebug_backtrace(), but I’m highlighting it here as it can be used in other non-Drupal PHP code too.

If you combine the devel module with the powerfull debug_backtrace() function from PHP, you have a neat way for a stack trace in your code. The stack trace is the complete path of functions there were called to finally end up at the point you enter the debug_backtrace in your code:

function foo($bar) {
  dpm (debug_backtrace()); // Show the backtrace up to here
  print_r (debug_backtrace()); // For non-Drupal code
  var_dump (debug_backtrace()); // Probably too much info

2. PHP extensions

Next to Drupal modules and PHP functions, there are also some extra PHP extensions you can install to make developing and debugging a whole lot easier.


Xdebug is a PHP extension that allows you to debug and profile PHP scripts with an external program. Profiling means getting a clear overview of what functions were called in your script, how many times, how much memory they used and how much cpu time.

Xdebug also makes your PHP error messages a bit nicer with adding a table layout and a call stack:

A normal PHP fatal error:

![A normal PHP fatal error][normal-screenshot] [normal-screenshot]: /wp-content/uploads/2015/05/Screenshot-2015-05-06-22.15.09.png

A PHP fatal error with the xdebug extension installed:

![A PHP fatal error with the xdebug extension installed][xdebug-screenshot] [xdebug-screenshot]: /wp-content/uploads/2015/05/Screenshot-2015-05-06-22.13.41.png

To enable this you need to enable the xdebug (duh) module and set these options in your php.ini:

display_errors = on
html_errors = on

For an overview of xdebug debugging and profiling, check this blog post again, it has instructions and screenshots how to set it up.

Xdebug is quite a must-have on every PHP development server or environment. Do not install xdebug on your production server! You will never display errors on a production server, nor debug code with an external editor, so don’t waste resources on loading this on a production site.


Xhprof is a profiling extension for PHP, made by Facebook.

The output is quite raw and it’s not easy to install, but it can provide you with some valuable information. It used to be one of the first PHP profiling tools, and worked quite well, but nowadays there are a lot better tools available (see the next section of this blog item).

I consider this extension to be ‘past its prime’ and it’s only listed here because it’s a popular tool and I wanted to cover it in my list of available tools. There is also Drupal module for it, but I found the xhprof support in the devel module to be better.

The same remark as xdebug goes for xhprof as well: do not install it on a production server!

3. External webservices

New Relic

New Relic is an online tool that you can use to monitor and profile applications and servers. It supports PHP and Linux servers and I’ve gotten quite fond of it lately.

Because it’s a daemonized process, that doesn’t really impact the performance of your server, you can install it on both development and production servers. The main things I nowadays use this tool for are:

  • Profiling code on production servers: why is a page slow?
  • Monitoring performance of applications and servers, combined with alerting: if a site suddenly starts throwing PHP errors, or page loads are below a predefined threshold, we get an email.
  • Continous API and website testing: test scripted scenario’s every x minutes to see if applications are still working like they should.

I will write a separate blog post about New Relic soon, as there is just way too much to cover in this blog post. I do encourage you to make a free account and just started testing on your own. You can install it on your production server or on your local PHP vagrant box. is the new kid on the block. It’s made by the creators of the Symfony framework and is mainly targetted at Symfony development, but you can use it for generic PHP development too.

I haven’t tested this for real projects yet, but it looks very promising so I’m mentioning it here. As Drupal 8 is built upon the Symfony kernel I expect this to become a popular debugging tool for Drupal. But we’ll have to see about that when Drupal 8 is actually released.

That’s all, I hope you learned something for this post.

comments powered by Disqus