This is a work in progress. Orange text needs updating.
When your code isn't doing what you want it to do, it's time to debug.
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
There are lots of options for debugging and there is lots you can do
without setting up a sophisticated debugging environment. This chapter
without setting up a sophisticated debugging environment. This chapter
contains some simple debugging tips and tricks to get you started and
contains some simple debugging tips and tricks to get you started and
also instructions on setting up XDebug, which is the recommended
also instructions on setting up XDebug, which is the recommended
debugging tool for CiviCRM when you have bugs which you are finding it
debugging tool for CiviCRM when you have bugs which are really hard to squish.
really hard to squish.
## UI options
!!! danger "Security Alert"
None of these debugging should be performed on production sites, as they can expose system configuration and authentication information being to unauthorized visitors.
These tools are activated by adding parameters to the URL that makes up
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.
the page, e.g. `&backtrace=1`. Go to **Administer > System Settings >
Debugging and Error Handling** to enable these options, and find out
more about them.
#### **Enable Debugging**
!!! danger "Security Alert"
Debug should **NOT** be enabled for production sites as it can result in system configuration and authentication information being exposed to unauthorized visitors.
CiviCRM has a debug mode which can be enabled to give you quick access
## Changing settings in the UI
to a couple of useful diagnostic tools, including access to all the
smarty variables that make up a page. It also provides shortcut methods
to empty the file based cache and session variables.
Available debug commands are listed in the info box below.
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.
**Debug URLs**
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.
Debug output is triggered by adding specific name-value pairs to the CiviCRM query string **when Enable Debugging is set to Yes**:
- Smarty Debug Window - Loads all variables available to the current page template into a pop-up window. To trigger, add `&smartyDebug=1` to any CiviCRM URL query string. Make sure you have pop-up blocking disabled in your browser for the CiviCRM site URL.
### Using URL parameters
- Session Reset - Resets all values in your client session. To trigger, add `&sessionReset=2`
- To empty template cache `civicrm/templates_c` folder), add `&directoryCleanup=1`
- To remove temporary upload files (`civicrm/upload` folder), add `&directoryCleanup=2`
- To cleanup both, add `&directoryCleanup=3`
- Stack Trace - To display a stack trace listing at the top of a page, add `&backtrace=1`
- Display Current Session - Displays the current users session variables in the browser, `&sessionDebug=1`
After enabling debugging, append any of the following name-value pairs to the URL for the page you visit.
**Forcing debug output**
-`&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.
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 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, after you have overridden the correct .tpl file, simply add `{debug}` to any part of the file and the Smarty Debug Window will display all variables in the same scope as the `{debug}` statement.
!!! 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 a ampersand.
#### Display Backtrace
### Displaying a backtrace
!!! danger "Security Alert"
The backtrace can be enabled independently of debugging. If this option is selected, a backtrace will be displayed even if debugging is disabled.
Backtrace should **NOT** be enabled for production sites as it can result in information being exposed to unauthorized visitors.
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.
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.
Set this to Yes if you want to display a backtrace listing when a fatal
## Viewing log files
error is encountered. This feature should **NOT** be enabled for
production sites.
You can also force the backtrace to be printed at any point in the code
CiviCRM's log files are stored in the `civicrm/ConfigAndLog` directory
by adding a call to `CRM_Core_Error::backtrace();`
(below the `files` directory in Drupal sites, and below the `media`
directory in Joomla sites and under `wp-content/plugins/files/` directory
in Wordpress). 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.
## Statements to insert into you code
**Forcing debug output**
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 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, after you have overridden the correct `.tpl` file, simply add `{debug}` to any part of the file and the Smarty Debug Window will display all variables in the same scope as the `{debug}` statement.
## Changing file-based settings
You can also force the backtrace to be printed at any point in the code
The following values can be added to your site's settings file `civicrm.settings.php` to assist in debugging:
by adding a call to `CRM_Core_Error::backtrace();`
-`define('CIVICRM_MAIL_LOG', 1);` causes all outbound CiviCRM email to be written to a log file. No real emails are sent.
### Settings which modify CiviCRM behavior for debugging
-`define('CIVICRM_MAIL_LOG', '/dev/null');` causes all outbound emails to be discarded. No email is sent and emails are not written to disk.
The following values can be added to your site's settings file
-`define( 'CIVICRM_DEBUG_LOG_QUERY', 1 );` outputs all SQL queries to a log file.
`civicrm.settings.php` to assist in debugging:
**Output all email to disk files OR discard**
-`define( 'CIVICRM_DEBUG_LOG_QUERY', 'backtrace' );` will include a backtrace of the PHP functions that led to the query.
`define('CIVICRM\_MAIL\_LOG', 1);`
-`define('CIVICRM_DAO_DEBUG', 1);` writes out various data layer queries to your browser screen.
This setting causes all outbound CiviCRM email to be written to files on your server's disk drive (Send Email to Contacts, Contribution and Event receipts, CiviMail mail ...). No real emails are sent. Emails are written to the `files/civicrm/ConfigAndLog/mail` (Drupal) or `media/civicrm/ConfigAndLog` directory (Joomla) by default.
!!! tip
When any sort of "logging stuff to a file" is enabled by one of the above settings, check the following directories for the resulting file:
`define('CIVICRM_MAIL_LOG', '/dev/null');`
- Drupal: `files/civicrm/ConfigAndLog/`
- Joomla: `media/civicrm/ConfigAndLog/`
This setting causes all outbound emails to be discarded. No email is sent and emails are NOT written to disk.
**Output all sql queries run by CiviCRM to a `CiviCRM.*.log` file**
## Viewing a query log from MySQL
Log files are located in the `files/civicrm/ConfigAndLog/` directory by default.
Outside of CiviCRM, the MySQL database software has features to enable the logging of all queries it receives.
This setting will include a backtrace of the php functions that led to this query.
`define('CIVICRM_DAO_DEBUG', 1);`
## Changing source code
Writes out various data layer queries to your browser screen.
### In Smarty template files
In many cases enabling MySQL query logging can be more effective.
Add `{debug}` to any part of the `.tpl` file and the Smarty Debug Window (described above) will display all variables in the same scope as the `{debug}` statement.
