Tips and Tricks

There are a few practices that seasoned CiviCRM developers have found very helpful when working on CiviCRM projects. This chapter contains a few of them, as well as some guidance on how to make use of them yourself. You don't have to use any of these tips, but they have made many other developers' lives easier, so give them a try and see if you agree.

Run a Local Development Instance of CiviCRM

When hacking on CiviCRM customizations and extensions, you don't want to interrupt your users' work or corrupt the data in the CiviCRM database. That's why you should never, ever hack on the same instance of CiviCRM that other people are using to store and work with live data. That's a recipe for disaster. Instead, load CiviCRM and its associated programs onto your own development "sandbox," where you can do whatever you want to CiviCRM without disturbing anyone else.

If your computer runs Linux or Mac OS X, running CiviCRM on your local machine is pretty easy. If your computer runs Windows, you have a little more work to do, but it's not impossible. You should seriously consider running Linux inside a virtual machine (there's a free program called VirtualBox that makes this pretty easy). We recommend running the latest version of Ubuntu Linux inside the virtual machine. You can download that here: http://www.ubuntu.com/

Preparing your machine to run CiviCRM

These instructions will tell you how to prepare your system to run CiviCRM. Jump to the section that matches your operating system.

Debian / Ubuntu Linux

sudo apt-get install apache2 php5 libapache2-mod-php5 mysql-server \
libmysqlclient15-dev php5-mysql php-db

Red Hat / CentOS Linux

sudo yum install php-xml

Mac OS X

Mac OS X does not have a built-in package manager like most Linux distributions do, but there are some third-party ones you can install. MacPorts is a good choice. The installation instructions can be found here: http://www.macports.org/install.php

Once MacPorts is installed, open up Terminal (in Applications -> Utilities) and run this command (quit Terminal first and re-launch it if you already had it running):

sudo port install apache2 mysql5-server php52 +pear +mysql5

Be sure to read the output of that command carefully, because there are often further tasks you need to perform to enable some of the packages (especially PHP and MySQL).

Next Step for All Operating Systems

Follow the CiviCRM installation instructions already provided in the documentation. You can find these instructions here: http://wiki.civicrm.org/confluence/display/CRMDOC/Installation+and+Upgrades

Use XDebug

This is our main recommendation for developers. 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: http://xdebug.org/docs/install

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 Systems

Tell XDebug to start automatically (don't do this on a production server!) by adding the following two lines to your php.ini file:

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 http://www.netbeans.org/

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: http://www.bluestatic.org/software/macgdbp/

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.

Debugging Tips

Note that to use these tips this you need to enable your Debugging in CiviCRM.

• Smarty Debug Window
  Loads all variables available to the current page template into a pop-up window. To create this window, add &smartyDebug=1 to any CiviCRM URL query string. Make sure you disable pop-up blocking in your browser for the CiviCRM site URL.
• Session Reset
  Resets all values in your client session. To trigger this, add &sessionReset=2
  
• Directory Cleanup
  Empties the template cache and/or the temporary upload file folders.
  
  • To empty template cache (the civicrm/templates_c folder), add &directoryCleanup=1
  • To remove temporary upload files (the civicrm/upload folder), add &directoryCleanup=2
  • To clean up both, add &directoryCleanup=3
• Stack Trace
  To display a stack trace listing at the top of a page, add &backtrace=1
  

Log emails to a file

For this you need to modify your CiviCRM settings (http://civicrm.settings.php) and add following line:

define('CIVICRM_MAIL_LOG', '<path to of the file >/mail.log');

Check the queries fired by Dataobject

define( 'CIVICRM_DAO_DEBUG', 1 );

Foreign constraint errors

If you are getting foreign key constraint errors, try logging out from CiviCRM and logging in again.

How to find the template file

Finding which template is used on a given page can be difficult. The easiest way is to view the source of the page from a web browser and search for ".tpl". For instance, for the contact summary page, use the web browser to access the contact summary page, then click "View Source" in the browser.  You should find an HTML comment such as:

<!-- .tpl file invoked: CRM/Contact/Page/View/Summary.tpl. Call via form.tpl 
    if we have a form in the page. -->

Use a source code management system

The source code of CiviCRM is accessible via Subversion. Although installing Subversion on your own computer is a bit complex, it is worthwhile using source control for your development website.

You should also use a local source code manager (git or mercurial are good solutions) to keep track of your modified files. The workflow that has been proven most efficient is to copy the original file, add it to your repository and then modify it.