Skip to content
Snippets Groups Projects
Select Git revision
  • master default protected
  • style_typo_edits
  • cherry-pick-732ddc4d
  • cherry-pick-79dd1516
  • cherry-pick-4160a494
  • import
  • queue1
  • github/fork/greenpeace-cee/clarify-output-encoding
  • mattwire-patch-4
  • mattwire-patch-3
  • mattwire-patch-2
  • mattwire-patch-1
  • revert-786-alterCustomFieldDisplayValue
13 results
Blame Permalink
debugging.md 20.42 KiB

Debugging

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 are really hard to squish.

!!! danger "Security Alert" None of these debugging methods should be performed on production sites, as they can expose system configuration and authentication information to unauthorized visitors.

The debugging methods presented here are ordered with the easiest ones first, but you may find the more challenging methods near the end to be more rewarding.

Changing settings in the UI

CiviCRM has a debug mode which can be enabled via the UI to give you quick access to a couple of useful diagnostic tools, including all the Smarty variables that make up a page. It also provides shortcut methods to empty the file-based cache and session variables.

To use debugging via the UI, first go to Administer > System Settings > Debugging and Error Handling to enable these options, and find out more about them.

Using URL parameters

After enabling debugging, append any of the following name-value pairs to the URL for the page you visit.

  • &smartyDebug=1 opens the Smarty Debug Window which loads all variables available to the current page template into a pop-up window (make sure you have pop-up blocking disabled).
  • &sessionReset=2 resets all values in your client session.
  • &directoryCleanup=1 empties template cache in civicrm/templates_c.
  • &directoryCleanup=2 removes temporary upload files in civicrm/upload.
  • &directoryCleanup=3 performs both of the above actions.
  • &backtrace=1 displays a stack trace listing at the top of a page.
  • &sessionDebug=1 displays the current users session variables in the browser.
  • &angularDebug=1 displays live variable updates on certain Angular-based pages.

!!! tip "Caveats" - Sometimes using &smartyDebug=1 to inspect variables available to a template will not work as expected. An example of this is looking at the Contact Summary page, when using this method will display the variables available only to the summary tab and you might want to see the variables available to one of the other tabs. To do this you will need to debug via code, as explained below. - If the page you are debugging does not already have a key-value parameter before debugging, you will need to begin the first parameter with a question mark instead of an ampersand.

Displaying a backtrace

The backtrace can be enabled independently of debugging. If this option is selected, a backtrace will be displayed even if debugging is disabled.

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.

Viewing log files

CiviCRM's log files are stored in the ConfigAndLog directory within CiviCRM's local file storage (see the File System documentation for details on your CMS). Most runtime errors are logged here, as well as data that you explicitly write to log using the CRM_Core_Error::debug log=true parameter.

One may also write to the log file without creating an error with: Civi::log()->debug(__FUNCTION__); This example will write the function-name to ConfigAndLog using the PHP constant, __FUNCTION__.

Changing file-based settings

The following values can be added to your site's settings file civicrm.settings.php to assist in debugging:

  • define('CIVICRM_MAIL_LOG', 1); causes all outbound CiviCRM email to be written to a log file. No real emails are sent.

  • define('CIVICRM_MAIL_LOG', '/dev/null'); causes all outbound emails to be discarded. No email is sent and emails are not written to disk.

  • define('CIVICRM_DEBUG_LOG_QUERY', 1); outputs all SQL queries to a log file.

  • define('CIVICRM_DEBUG_LOG_QUERY', 'backtrace'); will include a backtrace of the PHP functions that led to the query.

  • define('CIVICRM_DAO_DEBUG', 1); writes out various data layer queries to your browser screen.

  • define('CIVICRM_CONTAINER_CACHE', 'never'); causes Civi to rebuild the container from the latest data on every page-load.