Unsticking Yourself as a Drupal Developer: Googling & Getting Feedback
This post is being written for a presentation at the Western Massachusetts Drupal Camp on Jan. 22, 2011. It aims to share tips on getting yourself out of specific problems everyone encounters working as a developer with Drupal sites. Your presenter, Steve Cronen-Townsend a.k.a. crotown, was a Drupal freelancer for almost two years, and a few weeks ago joined Imbee as a full-time software engineer developing their Drupal-based web site.
Case study: Turning off Drupal's login block
One of the first things a person learns about using core Drupal, is going to the blocks page at /admin/build/block (navigation Administer->Site building->Blocks) and enabling, disabling, and moving blocks around on the pages of a freshly-installed Drupal web site. Disabling the login block and not knowing how to log in to administration account (the first account created) is a right-of-passage I suspect all Drupallers go through.
Image you are locked out of your newly-installed Drupal site because you turned of the login block and you don't know how to log in. Suppose you try this search on Google. I've used the query "User login block Drupal" [note: capitalization does not matter for Google searches]. Note that the second hit in the list, How do I get the User Login block back, is exactly what we wanted to know. If we go to that page, we discover that one can always log on to an (unmodified!) Drupal site by visiting "example.com/?q=user". I will address how I arrived at that particular search in the next section. But first, and most importantly, let me continue with an important principle.
Realize that many other people have been in the exact same situation, and have published their solution on the web.
Part 1: Searching How-To
Goal: Search for the "exact" issue, concisely
- Specific terms / keywords
- Precise terms. (e.g. check /admin/build/block for precise name "User login block")
- Add "Drupal" to web-wide searches
- Learn keywords from early search results, improve search query
- Ask friends for the right keyword (e.g. FOUC for "Flash of Unstyled Content")
- Jump close to the answer
- Project pages on drupal.org (modules and more), http://drupal.org/project/[name-of-project], e.g. http://drupal.org/project/admin_menu
- Drupal handbook pages at http://drupal.org/documentation
- API Documentation at http://api.drupal.org
- PHP Documentation at http://php.net.
Jumping is often inferior to Google search. But at least recognize the above places as authoritative.
- Anything you can learn about searching is worthwhile (e.g. Query syntax. Useful sites.)
Part 2: Crashes and errors
The topic here is debugging and I want to start it with the most important thing I can say about it:
Demand feedback on crashes. Starting point of any fix is always exact knowledge of what is happening.
Part of the reasoning behind adhering to this principle is that once you know exactly is going on you can conduct an effective Web search to find the answers others have published on the same situation (Part 1 of this talk). The other main idea behind this principle is that web sites are such complex systems (lots of code files, several languages, different layers of software, possibility of communicating with other web sites, etc...) that trying to fix a problem by changing something that you think may help the problem often leads to greater confusions and problems, rather than fixing the original issue. Let your experience guide you, but my experience says that nearly always you should get exact feedback on the error occurring before proceeding to fix it. As we all know, it is often challenging when you start with full feedback.
The feedback you get often tells you that PHP has an issue with a certain line of code, identified by source file path and line number. Follow my final principle of unsticking yourself:
Read the source code.
You have access to all the source code. Take full advantage of this and read it when you have the slightest question about how it works.
Feedback from Drupal
By feedback from Drupal, I mean feedback you can get from any Drupal sight by logging in as a user with administration permissions and visiting certain web pages.
The first of these is the Status page at /admin/reports/status and navigated to with Administer >> Reports >> Status report. This page provides a wealth of information that is particularly handy when first setting up a Drupal site. The idea here is that each of the colored lines should be green, unless you have a good reason for it not to be. For example, having modules that need a security update will make the appropriate line turn red, and you should always apply security fixes to make that same line turn (at least yellow). Yellow means, in this case, that some of your modules are out-of-date. You may well know that updating a certain module makes it incompatible with another module you use. If that is the case, you should probably be satisfied with the yellow line.
The other main way of getting feedback from the Drupal site is the "watchdog" error log accessed at /admin/reports/dblog and navigated with Administer >> Reports >> Recent log entries. Obviously this site is confused about a file that is expected to have the path /sites/crotown.com/files/submit-button.png but does not (ever since this site was converted from being part a multisite to being a stand-alone site.)
Feedback from PHP
By this I mean four things: information about the PHP install, the PHP error log and error pages, debugging print statements, and source-level debugging:
- information about the PHP installation your web server is using
For this case, you may use PHP's built-in phpinfo() command as described in this blog post. Sometimes you can simply ask your environment to display the output of phpinfo() for you by clicking a button. In any case, the HTML page you get will look something like this. This feedback may direct you, for example, to install a certain PHP module. Use the first principle and conduct a web search, and add the name of your operating system to the search query.
- The PHP error log and error web pages
The simplest and most helpful thing is often to turn on PHP's error web pages. This will usually replace a White Screen of Death (WSoD) with an error page from PHP telling you exactly what went wrong and caused PHP to crash. As usual, everything you need to know as a Drupaller about WSoD is on drupal.org:
To enable error reporting, temporarily edit your index.php file (normally located in your root directory) directly after the first opening PHP tag (do not edit the actual file info!) to add the following:
<?php error_reporting(E_ALL); ini_set('display_errors', TRUE); ini_set('display_startup_errors', TRUE); // $Id: index.php,v 1.94 2007/12/26...
You will now be able to see any errors that are occurring directly on the screen. Memory problems may still not be displayed, but it's the first step in a process of elimination.
This just a small sampling of the massive amount of debugging wisdom at http://drupal.org/node/158043. Reading it thoroughly will save you huge amounts of time as a Drupal developer.
The other important thing to know about PHP errors is that they can be logged but that often you will have to turn on that logging and, obviously, you will have to know where that log is stored.
Use the techniques above see the output of phpinfo() for the PHP that your web server uses. Find the line called "Configuration File(php.ini) Location" and edit that file. Look for the following lines containing error and make sure the two lines given are set correctly for your system:
; Default Value: E_ALL & ~E_NOTICE ; Development Value: E_ALL | E_STRICT ; Production Value: E_ALL & ~E_DEPRECATED ; <a href="http://php.net/error-reporting" title="http://php.net/error-reporting">http://php.net/error-reporting</a> error_reporting = E_ALL | E_STRICT
; Besides displaying errors, PHP can also log errors to locations such as a ; server-specific log, STDERR, or a location specified by the error_log ; directive found below. While errors should not be displayed on productions ; servers they should still be monitored and logging is a great way to do that. ; Default Value: Off ; Development Value: On ; Production Value: On ; <a href="http://php.net/log-errors" title="http://php.net/log-errors">http://php.net/log-errors</a> log_errors = On
This should get you started. Remember that the web server must have permission to write the log where you put it. Search (Principle #1) when you have questions.
- Debugging print statements
Putting debugging print statements in your code is the simplest way to get that exact feedback you need about what is going when PHP code executes. In increasing order of sophistication you have, basically, four choices:
- Source-level debugging
Get this capability. Remember that you must become all-powerful with PHP as a Drupal developer. You sometimes need to seed the code run line-by-line, change the values of variables in midstream, etc... To get this capability, start by asking around and search the web to find others who have succeeded setting it up (or buying it) with a system equivalent to yours.
Feedback from Apache
Here, we are talking about just getting logging to occur. As in the case of PHP, you may have to turn the logging on in order to get it. The ErrorLog directive is key. For Apache Version 2, start at http://httpd.apache.org/docs/2.0/logs.html.
As an example, on my server running Ubuntu 10.04 I did the following command to see where this directive was set:
cd /etc/apache2 egrep -r ErrorLog *
In the example of my Ubuntu-powered server the output of the above command has the answer all over it:
Feedback from MySQL
This case is not so crucial, since one can generally get the necessary feedback from the Devel module by visiting /admin/settings/devel and turning on Devel's "Collect query info" and "Display query log" and then visiting the page in question. The error log on my Ubuntu server has the default location of /var/log/mysql.err. And on my Mac using MAMP it's at /Applications/MAMP/logs/mysql_error_log.err. If you ever need to set up MySQL logging yourself, the information is at here and many other places on the Web.
The main insight of this presentation is that there are three principles underlying unsticking yourself as a Drupal developer. To recap, they are:
- Principle #1: Realize that many other people have been in the exact same situation, and have published their solution on the web.
- Principle #2: Demand feedback on crashes. Starting point of any fix is always exact knowledge of what is happening.
- Principle #3: Read the source code.
Remembering these three principles when facing issues with Drupal will give you a solid foundation for solving those issues.
A special thanks to Imbee for supporting my completion of this presentation.