From 39f99d70ed953896b8a9448c204e891ee491b2ee Mon Sep 17 00:00:00 2001
From: Sean Madsen <sean@seanmadsen.com>
Date: Fri, 13 Jan 2017 10:53:25 -0700
Subject: [PATCH] debugging: first pass clean up
---
docs/dev-tools/debugging.md | 180 +++++++++++++-----------------------
1 file changed, 64 insertions(+), 116 deletions(-)
diff --git a/docs/dev-tools/debugging.md b/docs/dev-tools/debugging.md
index 342c8305..b11b6e2a 100644
--- a/docs/dev-tools/debugging.md
+++ b/docs/dev-tools/debugging.md
@@ -1,47 +1,7 @@
# Debugging for developers
-**Table of Contents**
-
-- [UI options](#Debuggingfordevelopers-UIoptions)
-
-- [**Enable Debugging** ](#Debuggingfordevelopers-EnableDebugging)
-- [Display Backtrace](#Debuggingfordevelopers-DisplayBacktrace)
-
-- [Statements to insert into you
- code](#Debuggingfordevelopers-Statementstoinsertintoyoucode)
-
-- [Settings which modify CiviCRM behavior for
- debugging](#Debuggingfordevelopers-SettingswhichmodifyCiviCRMbehaviorfordebugging)
-
-- [Printing PHP
- variables](#Debuggingfordevelopers-PrintingPHPvariables)
-
-- [Log files](#Debuggingfordevelopers-Logfiles)
-- [Clearing the cache](#Debuggingfordevelopers-Clearingthecache)
-- [Check the queries fired by
- Dataobject](#Debuggingfordevelopers-CheckthequeriesfiredbyDataobject)
-- [Setting up a debugger and front
- end](#Debuggingfordevelopers-Settingupadebuggerandfrontend)
-- [XDebug](#Debuggingfordevelopers-XDebug)
-
-- [What is a debugger?](#Debuggingfordevelopers-Whatisadebugger?)
-- [Setting Up XDebug](#Debuggingfordevelopers-SettingUpXDebug)
-
-- [Debian / Ubuntu Linux](#Debuggingfordevelopers-Debian/UbuntuLinux)
-- [Red Hat / CentOS Linux](#Debuggingfordevelopers-RedHat/CentOSLinux)
-- [Mac OS X](#Debuggingfordevelopers-MacOSX)
-- [Next Step for All Operating System
- ](#Debuggingfordevelopers-NextStepforAllOperatingSystem)
-
-- [Installing an XDebug
- Front-End](#Debuggingfordevelopers-InstallinganXDebugFront-End)
-
-- [All Operating Systems](#Debuggingfordevelopers-AllOperatingSystems)
-- [Mac OS X](#Debuggingfordevelopers-MacOSX.1)
-
- ----------------------------------------------------- ----------------------------------------------------------
-  This is a work in progress. Orange text needs updating.
- ----------------------------------------------------- ----------------------------------------------------------
+!!! warning
+ 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.
There are lots of options for debugging and there is lots you can do
@@ -54,18 +14,14 @@ really hard to squish.
## UI options
These tools are activated by adding parameters to the URL that makes up
-the page, e.g. &backtrace=1. Go to **Administer \> System Settings \>
+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**
-
-
- ------------------------------------------------------- ----------------------------------------------------------------------------------------------------------------------------------------------------------------------
-  **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.
- ------------------------------------------------------- ----------------------------------------------------------------------------------------------------------------------------------------------------------------------
+!!! 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
to a couple of useful diagnostic tools, including access to all the
@@ -74,32 +30,28 @@ to empty the file based cache and session variables.
Available debug commands are listed in the info box below.
- --------------------------------------------------------- --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-  **Debug URLs**\
- Debug output is triggered by adding specific name-value pairs to the CiviCRM query string **when Enable Debugging is set to Yes**:
+**Debug URLs**
+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.
- - Session Reset - Resets all values in your client session. To trigger, add *&sessionReset=2*
- - Directory Cleanup - Empties template cache and/or temporary upload file folders.
- - 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*
+- 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.
+- Session Reset - Resets all values in your client session. To trigger, add `&sessionReset=2`
+- Directory Cleanup - Empties template cache and/or temporary upload file folders.
+ - 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`
- --------------------------------------------------------- --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
- --------------------------------------------------------- ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-  **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.
- --------------------------------------------------------- ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+**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.
#### Display Backtrace
- ------------------------------------------------------- ----------------------------------------------------------------------------------------------------------------------------------
-  **Security Alert**\
- Backtrace should **NOT** be enabled for production sites as it can result in information being exposed to unauthorized visitors.
- ------------------------------------------------------- ----------------------------------------------------------------------------------------------------------------------------------
+!!! danger "Security Alert"
+ Backtrace should **NOT** be enabled for production sites as it can result in information being exposed to unauthorized visitors.
+
The backtrace can be enabled independently of debugging. If this option
is selected, a backtrace will be displayed even if debugging is
@@ -115,59 +67,58 @@ 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
-by adding a call to "CRM\_Core\_Error::backtrace();"
+by adding a call to `CRM_Core_Error::backtrace();`
## 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.
- --------------------------------------------------------- ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+**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.
You can also force the backtrace to be printed at any point in the code
-by adding a call to "CRM\_Core\_Error::backtrace();"
+by adding a call to `CRM_Core_Error::backtrace();`
+
### Settings which modify CiviCRM behavior for debugging
The following values can be added to your site's settings file
-(civicrm.settings.php) to assist in debugging:
+`civicrm.settings.php` to assist in debugging:
+
+**Output all email to disk files OR discard**
+
+`define('CIVICRM\_MAIL\_LOG', 1);`
- --------------------------------------------------------- -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-  **Output all email to disk files OR discard**\
- define('CIVICRM\_MAIL\_LOG', 1);\
- 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.
+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.
- define('CIVICRM\_MAIL\_LOG', '/dev/null');\
- This setting causes all outbound emails to be discarded. No email is sent and emails are NOT written to disk.
- --------------------------------------------------------- -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+`define('CIVICRM_MAIL_LOG', '/dev/null');`
- --------------------------------------------------------- -------------------------------------------------------------------------------------
-  **Output all sql queries run by CiviCRM to a CiviCRM.\*.log file**\
- Log files are located in the files/civicrm/ConfigAndLog/ directory by default.
+This setting causes all outbound emails to be discarded. No email is sent and emails are NOT written to disk.
- define( 'CIVICRM\_DEBUG\_LOG\_QUERY', 1 );
+**Output all sql queries run by CiviCRM to a `CiviCRM.*.log` file**
- define( 'CIVICRM\_DEBUG\_LOG\_QUERY', 'backtrace' );\
- This setting will include a backtrace of the php functions that led to this query.
- --------------------------------------------------------- -------------------------------------------------------------------------------------
+Log files are located in the `files/civicrm/ConfigAndLog/` directory by default.
+`define( 'CIVICRM_DEBUG_LOG_QUERY', 1 );`
+`define( 'CIVICRM_DEBUG_LOG_QUERY', 'backtrace' );`
-define('CIVICRM\_DAO\_DEBUG', 1);\
- Writes out various data layer queries to your browser screen.
+This setting will include a backtrace of the php functions that led to this query.
- --------------------------------------------------- -------------------------------------------------------------------
-  In many cases enabling MySQL query logging can be more effective.
- --------------------------------------------------- -------------------------------------------------------------------
+`define('CIVICRM_DAO_DEBUG', 1);`
+
+Writes out various data layer queries to your browser screen.
+
+In many cases enabling MySQL query logging can be more effective.
#### 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.
+`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
+Following your `print_r();` with and `exit;` to stop the script execution
at that point is often useful or necessary.
The `var_dump()` function gives similar output to `print_r()` but also
@@ -176,11 +127,11 @@ really useful during debugging.
## Log files
-CiviCRM's log files are stored in the *civicrm/ConfigAndLog* directory
-(below the *files* directory in Drupal sites, and below the *media*
-directory in Joomla sites and under wp-content/plugins/files/ directory
+CiviCRM's log files are stored in the `civicrm/ConfigAndLog` directory
+(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
+you explicitly write to log using the `CRM_Core_Error::debug log=true`
parameter.
## Clearing the cache
@@ -188,13 +139,13 @@ parameter.
Using Drupal, you can clear all caches with the following **drush**
command :
-- drush cc civicrm
-- drush civicrm-cache-clear *(older versions only)*
+- `drush cc civicrm`
+- `drush civicrm-cache-clear` *(older versions only)*
Alternatively, you can call the following two methods:
-- CRM\_Core\_Config::clearDBCache();
-- CRM\_Core\_Config::cleanup();
+- `CRM_Core_Config::clearDBCache();`
+- `CRM_Core_Config::cleanup();`
which clear the database and file cache respectively.
@@ -252,8 +203,7 @@ systems listed here.
#### Red Hat / CentOS Linux
sudo yum install php-pecl* php-devel php-pear
-
-sudo pecl install Xdebug
+ sudo pecl install Xdebug
#### Mac OS X
@@ -262,17 +212,15 @@ sudo pecl install 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
+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.
@@ -295,7 +243,7 @@ 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
+breakpoint in `CRM/Core/Invoke.php` to make the debugger pause there. For
more information, see the NetBeans debugging documentation.
#### Mac OS X
--
GitLab