1. Forensic Drupal Debugging Dan Harris dharris1@stanford.edu daneesia on drupal.org

2. Agenda Basic Principles: what are the clues Basic Principles: what are the clues Drupal UI Configuration Drupal UI Configuration White Screen of Death (WSOD) White Screen of Death (WSOD) Debugging with Themer/Devel Debugging with Themer/Devel Q&A Session Q&A Session

3. What’s NOT Covered Javascript bugs Javascript bugs HTML/CSS bugs HTML/CSS bugs Using a tool with breakpoints to step through code execution Using a tool with breakpoints to step through code execution Performance debugging Performance debugging Anything not mentioned on the previous slide Anything not mentioned on the previous slide

4. Reviewing Trace Evidence Some or all of the following are part of rendering a Drupal page: Some or all of the following are part of rendering a Drupal page: –Drupal core, contributed, and custom modules/templates –HTML, CSS, and Javascript –PHP, Apache, some dB software, and the host OS –The browser and client OS –Host hardware and client hardware –Load balancers, external caching, networking equipment and protocols, etc. etc. All of them have versions All of them have versions All of them are possible culprits when something goes awry. All of them are possible culprits when something goes awry.

5. Reviewing Trace Evidence When something goes wrong, where do I look for clues? When something goes wrong, where do I look for clues? –Output is wrong or missing, check Input filter setting Input filter setting Template and CSS files: remember that files outside you’re theme have influence Template and CSS files: remember that files outside you’re theme have influence Permissions and configuration settings Permissions and configuration settings Use code to help you figure it out Use code to help you figure it out –Error message: Check log files (Drupal, PHP, dB) Check log files (Drupal, PHP, dB) Search the message on Drupal.org Search the message on Drupal.org –WSOD: in a few slides

6. Drupal 6 UI Configuration /admin/settings/error-reporting /admin/settings/error-reporting –Staging site: write errors to log and screen; –Production: write errors to the log only

7. Drupal 6 UI Configuration /admin/settings/performance /admin/settings/performance –Disable all caching/compression on staging (no need) –May selectively disable these when debugging on production Remember to flush caches when Remember to flush caches when –Introducing a new module/theme file –If you have caching enabled and change something like a menu

8. Drupal 6 UI Configuration /admin/settings/admin /admin/settings/admin –Consider using a separate theme for admin –I like Adaptivetheme for this purpose Some useful code if you use an admin module: Some useful code if you use an admin module: function YOURMODULE_init() { if ( (arg(0) == 'node' && arg(1) == 'add') || if ( (arg(0) == 'node' && arg(1) == 'add') || (arg(0) == 'node' && arg(2) == 'edit') || (arg(0) == 'node' && arg(2) == 'edit') || …) …) { if ($admin_theme = variable_get('admin_theme', 0)) { if ($admin_theme = variable_get('admin_theme', 0)) { global $custom_theme; global $custom_theme; $custom_theme = $admin_theme; $custom_theme = $admin_theme; drupal_add_css(); // Use to add custom CSS for your admin theme drupal_add_css(); // Use to add custom CSS for your admin theme } }}

9. Drupal Status Report and Logs /admin/reports/status & /admin/reports/dblog /admin/reports/status & /admin/reports/dblog Check these often, especially when Check these often, especially when –Site in development –First couple weeks after deployment

10. Gotcha when Using the Collaboration Tools Updating Drupal normally 2 steps Updating Drupal normally 2 steps –1) Update modules; 2)Run update.php It’s 3 steps for the Collab Tools It’s 3 steps for the Collab Tools –Run collab tool updater –Update modules not updated by collab tool –Run update.php Some people forget the third step! Some people forget the third step!

11. Debugging the WSOD A few things to try: A few things to try: –If you’re only getting it on a particular screen, check the log report and files –(Temporarily) paste the following into the top of index.php (after <?php): // Use the if for a multi-site; otherwise you just need the 3 lines if ($_SERVER['HTTP_HOST']==='some.domain.name.here') { error_reporting(E_ALL); ini_set('display_errors', TRUE); ini_set('display_startup_errors', TRUE);

12. Debugging the WSOD A few things to try: A few things to try: –Log on to the server and access the log files: tail /var/log/apache2/error.log –Check your dB & OS logs too –Additional resources: http://drupal.org/node/158043 http://drupal.org/node/158043 http://drupal.org/node/158043 http://drupal.org/node/482956 http://drupal.org/node/482956 http://drupal.org/node/482956 http://drupal.org/node/31819 http://drupal.org/node/31819 http://drupal.org/node/31819

13. Debugging with Themer

14. “Firebug for Drupal Theming” “Firebug for Drupal Theming” Theme hook called: indicates where and how you can hook into the execution. Theme hook called: indicates where and how you can hook into the execution. File used: template file used to generate this part of the page File used: template file used to generate this part of the page –Click the link to view the file Function called: click link to display API call on api.drupal.org Function called: click link to display API call on api.drupal.org Preprocess functions: functions called before the section is rendered Preprocess functions: functions called before the section is rendered –A word of caution: in a sub-theme, preprocess functions targeting the same area of execution (e.g. page) may both be run. Template variables provide valuable debug info Template variables provide valuable debug info

15. A word of Caution about Themer Enabling Themer can cause other bugs! Enabling Themer can cause other bugs! –Edit Content > Manage Fields: displays field weights –Edit Content > Display Fields: all messed up –Etc. Best to enable, use, then disable Best to enable, use, then disable –The Devel block provides such capability

16. Debugging with Devel Devel can provide the following: Devel can provide the following: –dB Query information –Highlight slow queries –Display page load times & memory usage –More information when PHP errors are generated via backtrace. –Functions to embed in your code and provide valuable debug information –Generate content!

17. Devel Function Calls dsm(), dpm(): print a variable out to an interactive UI dsm(), dpm(): print a variable out to an interactive UI Example: if (module_exists('devel')) dpm($node); dvm(): similar to dsm/dpm except uses var_dump() instead of print_r(). dvm(): similar to dsm/dpm except uses var_dump() instead of print_r(). dpr(): pretty print version of PHP print_r() call dpr(): pretty print version of PHP print_r() call Example: if (module_exists('devel')) dprint_r($_SESSION); dvr(): same as dpr, except uses var_dump(). dvr(): same as dpr, except uses var_dump(). dd(): write debug information out to a file dd(): write debug information out to a file Many many more: http://api.drupal.org/api/devel/devel.module/6 Many many more: http://api.drupal.org/api/devel/devel.module/6http://api.drupal.org/api/devel/devel.module/6 See also http://drupal.org/project/drupalforfirebug See also http://drupal.org/project/drupalforfirebughttp://drupal.org/project/drupalforfirebug

18. Problem Solving Best Practices Shamelessly stolen from http://randyfay.com/node/40 Shamelessly stolen from http://randyfay.com/node/40http://randyfay.com/node/40 –Keep a log of changes on the site. Note when a new module is installed a new module is installed a patch is applied a patch is applied an upgrade is done. an upgrade is done. Consider using the journal module to help with this. Consider using the journal module to help with this. journal –Keep your code under source control (Git). –Keep multiple backups of your database. Consider using the Backup and Migrate Consider using the Backup and Migrate Backup and MigrateBackup and Migrate –Try to have matching production, staging, and testing environments –Have a quick path to replicating production to another testing environment –Use a notebook to record changes when working through a complex debugging session.

19. Where to go from Here Join the Stanford Drupallers Group Join the Stanford Drupallers Group For hard-core debugging tips, view http://www.archive.org/details/TroubleshootingInDrupal For hard-core debugging tips, view http://www.archive.org/details/TroubleshootingInDrupal http://www.archive.org/details/TroubleshootingInDrupal –One tip from the video: never copy and paste code form Skype…you have been warned –One tip from the video: never copy and paste code form Skype…you have been warned –http://www.archive.org/details/DebuggingDrupal (Randy Fay) http://www.archive.org/details/DebuggingDrupal Ask on Drupal.ogr: Ask on Drupal.ogr: –If your question is directly related to a module, place a support request in the module issue queue –If more generic, use the Forums

20. Q&A Session

21. Thanks! Feel free to contact me: Feel free to contact me: –dharris1@stanford.edu dharris1@stanford.edu –95slug@gmail.com 95slug@gmail.com –daneesia on Drupal