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

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

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

4. Reviewing Trace Evidence • 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 are possible culprits when something goes awry.

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

6. Drupal 6 UI Configuration • /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 • Disable all caching/compression on staging (no need) • May selectively disable these when debugging on production • 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 • Consider using a separate theme for admin • I like Adaptivetheme for this purpose • Some useful code if you use an admin module: function YOURMODULE_init() { if ( (arg(0) == 'node' && arg(1) == 'add') || (arg(0) == 'node' && arg(2) == 'edit') || …) { if ($admin_theme = variable_get('admin_theme', 0)) { global $custom_theme; $custom_theme = $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 • 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 • 1) Update modules; 2)Run update.php • 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!

11. Debugging the WSOD • 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 linesif ($_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: • 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/482956 • http://drupal.org/node/31819

13. Debugging with Themer

14. Debugging with Themer • “Firebug for Drupal Theming” • 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 • Click the link to view the file • Function called: click link to display API call on api.drupal.org • 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

15. A word of Caution about Themer • 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 • The Devel block provides such capability

16. Debugging with Devel • 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 Example: if (module_exists('devel')) dpm($node); • dvm(): similar to dsm/dpm except uses var_dump() instead of print_r(). • 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(). • dd(): write debug information out to a file • Many many more: http://api.drupal.org/api/devel/devel.module/6 • See also http://drupal.org/project/drupalforfirebug

18. Problem Solving Best Practices • Shamelesslystolen from http://randyfay.com/node/40 • Keep a log of changes on the site. Note when • a new module is installed • a patch is applied • an upgrade is done. • Consider using the journal module to help with this.  • Keep your code under source control (Git). • Keep multiple backups of your database. • Consider using the Backup 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 • For hard-core debugging tips, view http://www.archive.org/details/TroubleshootingInDrupal • One tip from the video: never copy and paste code form Skype…you have been warned  • http://www.archive.org/details/DebuggingDrupal (Randy Fay) • 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: • dharris1@stanford.edu • 95slug@gmail.com • daneesia on Drupal