Debugging Drupal

There are generally two reasons you need more information on debugging. Either your site has gone haywire with error messages and WSOD (white screens of death), or you have mustered the courage to take a peek behind the magic curtain that makes Drupal so powerful and you are looking for the right tools. I will cover four topics:

  • Finding and applying patches

  • Searching error logs

  • DPM or KPR to view the underlying data structure

  • IDEs (Integrated Development Environment) for when DPM/KPR just doesn't cut it.

Before Jumping Down the Rabbit Hole: Try the three most common solutions for solving Drupal errors.

1. Clear the cache 2. Clear the cache 3. Clear the cache.

If three cache clears doesn't work, move on.

* There have been reports of 7-10 cache clears doing the trick, so YMMV

** If you can't access the admin interface then you should use Drush to clear the cache (drush cc all) from the command line. https://www.drupal.org/project/drush and detailed info: https://github.com/drush-ops/drush/blob/master/README.md

No Luck? Gather More Info: If you have a WSOD then you are probably looking at a fatal error in the PHP code that is keeping Drupal from rendering, well, anything. In this case you will probably want to read about searching error logs so you can find more useful information.

If you're lucky then you've received an error message with some details. You can now do a general search, or use Drupal.org.

For a general search: Pop the error message into your favorite search engine with your version of Drupal, e.g. (“Drupal 7 PDOException: in hcap_import_do() (line 215 of /modules/custom/hcap/hcap.module)”) and with luck someone will have already developed a solution. Stackoverflow.com is a great resource, along with many other sites. Most likely you will need to do some coding to implement these fixes.

Drupal.org: If your error specifies a specific module then there is a decent chance that the project page on drupal.org will have information in the module's issue queue. On the right hand side of the module page you will see “Issues for module_name”, and you can proceed to search for the problem. If you are very lucky, someone has already created a patch! If you don't find a patch and you have a testing environment, you can try the “dev” version of a module. Sometimes a dev version will have already fixed the issue. Do not apply dev versions to a live site as your problems may well get worse.

Applying Patches: Before you patch anything make a backup of the original code! If you are using version control (such as git) then good work, your code is backed up by design.

Now, if you are lucky enough to have found a patch for your problem then you can apply it in a test environment, verify that it works, then update the production site. For more info on applying patches go here https://www.drupal.org/patch/apply.

Searching Error Logs: If Drupal is not giving you an error message but something isn't working right, then start by checking Drupal's Reports section. First check the general site status at your_domain.com/admin/reports/status to see if there are any general site issues. For more specific error messages check your_domain.com/admin/reports/dblog. Here you will see php, security, and other messages with more technical information. Still not finding what you need, or unable to even access Drupal? Time to dig into the webserver!

Your webserver should log any errors and give you an idea of what went wrong. If you do not have SSH access to your webserver, or a local testing environment, you may be able to view the error logs through your hosting provider's control panel.

If you do have SSH access, or a local environment set up then you can probably access the error log directly.

Most servers are running on some version of linux, in which case you will often find the error log in the folder /var/log folder. For Apache it is probably /var/log/apache2/error.log, for Lighttpd: /var/log/lighttpd/error.log. The location of the log folder can vary, but some internet searches should help you find it.

Once you find the error log you will see a list of error messages with timestamps such as:

[Mon Sep 15 13:16:46.724027 2014] [:error] [pid 23169] [client 127.0.0.1:53635] PHP 17. _theme() /home/gabriel/sites/drupal8/core/includes/common.inc:3165, referer: http://localhost/drupal8/admin/modules

[Mon Sep 15 13:16:46.724030 2014] [:error] [pid 23169] [client 127.0.0.1:53635] PHP 18. back_to_parent_preprocess_page() /home/gabriel/sites/drupal8/core/includes/theme.inc:581, referer: http://localhost/drupal8/admin/modules

[Mon Sep 15 13:17:29.789500 2014] [:error] [pid 23067] [client 127.0.0.1:53692] PHP Fatal error: Call to undefined function variable_get() in /home/gabriel/sites/drupal8/modules/back_to_parent/back_to_parent.module on line 186

[Mon Sep 15 13:17:29.789519 2014] [:error] [pid 23067] [client 127.0.0.1:53692] PHP Stack trace:

[Mon Sep 15 13:17:29.789526 2014] [:error] [pid 23067] [client 127.0.0.1:53692] PHP 1. {main}() /home/gabriel/sites/drupal8/index.ph+p:0

[Mon Sep 15 13:17:29.789531 2014] [:error] [pid 23067] [client 127.0.0.1:53692] PHP 2. Drupal\\Core\\DrupalKernel->handle() /home/gabriel/sites/drupal8/index.php:23

Often the list is huge and its hard to find the message that will actually help you out! The best method I've found is to check your site and note the general time. Refresh the page where your errors are ocurring; this should generate another set of error messages with the current timestamp. Now scroll through the messages until you find where the time changes, and the most useful error message is generally the first in a series. Above you can see the time stamp change from 13:16:46 to 13:17:29. Its only about a minute difference, but timestamps for error messages usually don't span more than a second or two. In this case the relevant message is:

PHP Fatal error: Call to undefined function variable_get() in /home/gabriel/sites/drupal8/modules/back_to_parent/back_to_parent.module on line 186

Now I know that the module I was working on started to fail on line 186 of the file back_to_parent.module. Now you need to figure out what went wrong and how to fix it. In this case it is a PHP error where the module is calling a function that does not exist, so perhaps there is a typo or the function needs to be created. I will not cover these scenarios since there are too many and a good search would probably help you more.

One common error I run into when traversing Drupal data arrays/objects is this: Cannot use object of type stdClass as array. Or perhaps something is being referenced that doesn't even exist. These situations are where DPM/KPR/your IDE come into play.

DPM/KPR: These two utilities are quite similar and require the Devel module, a must for any Drupal developer www.drupal.org/project/devel. By now you should at least have a starting point for where to debug. You can use DPM or KPR to print the contents of variables directly on your site. For a good demonstration go to your site's theme folder and open the page template, page.tpl.php. Add the following code at any point, then go visit a node on your site, and you should see a printout of the node data structure.

<?php dpm($node); ?>

or

<?php kpr($node); ?>

This gives you much more friendly readout of the data than say, <?php print_r($node); ?> which uses PHP's method of data visualization that dumps out the structure as plain text. Often you will need to clear the cache, or refresh the page 1-2x before you see the results.

You can use this on any available variable to see what is happening. Maybe an object is referenced as an array, or maybe a variable hasn't even been created but is being referenced. Whatever is happening, these tools should help you find out the details. Check the Devel api documentation for even more useful items, along with this link from the project page http://ratatosk.net/drupal/tutorials/debugging-drupal.html.

IDE: The Devel module is a great tool, however it does not work for every situation. Sometimes you will be debugging code where a call to DPM gets wiped out before Drupal is able to render it. In these cases you can either save data in the globals or variables arrays, then access it further down the line, however this is cumbersome. Enter the IDE!

IDE's are basically advanced text editors that work with components like xdebug that let you stop your code at any point and see all available data. You can create breakpoints that let you view variable data before and after any part of your code. Does some function all your variable, then afterwards your module breaks? Use a breakpoint to view the data before and after the function call to see what happened to your data. With your favorite IDE you can go through your code line by line if needed and find out exactly where it breaks.

The installation and use of an IDE is an advanced topic best covered by many other sites, so I will give you a list of some popular PHP capable IDE's and quick overview of how to install.

Freely Available IDE's:

Netbeans

Eclipse

Aptana Studio (Eclipse derivative)

Paid IDE's:

phpDesigner

Jetbrains PHPStorm

Komodo IDE (has some free/flexible pricing scenarios)

Once you have reviewed the options these are the general steps:

  1. Install Xdebug

  2. Modify your php.ini config to enable xdebug

  3. Install your IDE, configure to use xdebug and a browser.

  4. Possibly a browser plugin for xdebug

There are more details for getting an IDE up and running, so search instructions regarding your OS and IDE of choice.

 

I hope this broad overview of debugging has provided some you with some useful information.