CiviCRM Developer Guide


When your code isn't doing what you want it to do, it's time to debug.  There are lots of options for debugging and there is lots you can do without setting up a sophisticated debugging environment.  This chapter contains some simple debugging tips and tricks to get you started and also instructions on setting up XDebug, which is the recommended debugging tool for CiviCRM when you have bugs which you are finding it really hard to squish.

Printing PHP variables

CRM_Core_Error::debug($name, $variable = null, $log = true, $html = true); can be called to print any variable. It is a wrapper around print_r($variable); which does some clever stuff, but print_r($variable); is often all you need.

Following your print_r(); with and exit; to stop the script execution at that point is often useful or necessary.

Debug mode

CiviCRM has a debug mode which you can enable to give you quick access to a couple of useful diagnostic tools, including access to all the smarty variables that make up a page, and access to the backtrace (read more about backtrace below). It also provides shortcut methods to empty the file based cache and session variables.

These tools are activated by adding parameters to the URL that makes up the page, e.g. &backtrace=1. Go to Admin > Global config > Debugging to enable debug mode and read more about the available options.

Printing smarty variables

When debug mode is enabled, you can display all the smarty variables that have been added to the page by adding  &smartyDebug=1 to any URL.


A backtrace is a list of all the functions that were run in the execution of the page, and the php files that contain these functions.  It can be really useful in understanding the path that was taken through code, what gets executed where, etc.

If display backtrace is enabled in Debugging options then the backtrace will be displayed when an error occurs.

You can also force the backtrace to be printed at any point in the code by adding a call to "CRM_Core_Error::backtrace();"

Clearing the cache

Using Drupal, you can clear all caches with the drush command civicrm-cache-clear.

Alternatively, you can call the following two methods:

  • CRM_Core_Config::clearDBCache();
  • CRM_Core_Config::cleanup();

which clear the database and file cache respectively.

Check the queries fired by Dataobject

define( 'CIVICRM_DAO_DEBUG', 1 );


XDebug is our main recommendation for developers that want to go into hardcore debugging. Readers familiar with what a debugger is and how it works should feel free to skip ahead to the "Setting Up XDebug" section.

What is a debugger?

A debugger is a software program that watches your code while it executes and allows you to inspect, interrupt, and step through the code. That means you can stop the execution right before a critical juncture (for example, where something is crashing or producing bad data) and look at the values of all the variables and objects to make sure they are what you expect them to be. You can then step through the execution one line at a time and see exactly where and why things break down. It's no exaggeration to say that a debugger is a developer's best friend. It will save you countless hours of beating your head against your desk while you insert print statements everywhere to track down an elusive bug.

Debugging in PHP is a bit tricky because your code is actually running inside the PHP interpreter, which is itself (usually) running inside a web server. This web server may or may not be on the same machine where you're writing your code. If you're running your CiviCRM development instance on a separate server, you need a debugger that can communicate with you over the network. Luckily such a clever creature already exists: XDebug.

Setting Up XDebug

XDebug isn't the only PHP debugger, but it's the one we recommend for CiviCRM debugging.

The instructions for downloading and installing XDebug are here:

Those instructions are a bit complex, however. There is a far simpler way to install it if you happen to be running one of the operating systems listed here.

Debian / Ubuntu Linux

sudo apt-get install php5-xdebug

Red Hat / CentOS Linux

sudo yum install php-pecl* php-devel php-pear

sudo pecl install Xdebug

Mac OS X

sudo port install php5-xdebug

Next Step for All Operating System

Tell XDebug to start automatically (don't do this on a production server!) by adding the following two lines to your php.ini file (your php.ini file is a php configuration file which is found somewhere on your server.  Calling the phpinfo() function is probably the  easiest way to tell you where this file is in your case.

xdebug.remote_enable = On
xdebug.remote_autostart = 1

Once XDebug is installed and enabled in your PHP configuration, you'll need to restart your web server.

Installing an XDebug Front-End

After you have XDebug running on your PHP web server, you need to install a front-end to actually see what it is telling you about your code. There are a few different options available depending on what operating system you use:

All Operating Systems

NetBeans is a heavyweight Java IDE (Integrated Development Environment). It offers lots of features, but isn't exactly small or fast. However, it is very good at interactive debugging with XDebug. And since it's written in  Java, it should run on any operating system you want to run it on. You can find it at

After installing NetBeans, open your local CiviCRM installation in NetBeans and click the Debug button on the toolbar. It will fire up your web browser and start the debugger on CiviCRM. You may went to set a breakpoint in CRM/Core/Invoke.php to make the debugger pause there. For more information, see the NetBeans debugging documentation.

Mac OS X

A much lighter-weight option for Mac users is a program called MacGDBp. You can download it here:

After installing MacGDBp, launch it and make sure it says "Connecting" at the bottom in the status bar. If it doesn't, click the green "On" button in the upper-right corner to enable it. The next time you access CiviCRM, the web browser will appear to hang. If you click on MacGDBp, you'll see that it has stopped on the first line of code in CiviCRM. From there you can step through the code to the part you're interested in. But it's probably a better idea to set a breakpoint in the part of the code you're interested in stopping at. See the MacGDBp documentation for more information.