CHAPTER 22 ■ DEVELOPMENT BEST PRACTICES

Semicolons

The PHP language requires semicolons at the end of most lines, but allows them to be omitted at the end of code blocks. Drupal coding standards require them, even at the end of code blocks.

Example URLs

Use example.com for all example URLs per RFC 2606.

Naming Conventions

Functions and variables should be named using lowercase, and words should be separated by an underscore. Functions should in addition have the grouping/module name as a prefix, to avoid name collisions between modules.

Persistent variables (variables/settings defined using Drupal’s variable_get()/variable_set() functions) should be named using all lowercase letters, and words should be separated with an underscore. They should use the grouping/module name as a prefix, to avoid name collisions between modules.

Constants should always be in all uppercase, with underscores to separate words. This includes predefined PHP constants like TRUE, FALSE, and NULL. Module-defined constant names should also be prefixed by an uppercase spelling of the module they are defined by.

Global variables should start with a single underscore followed by the module/theme name and another underscore.

Classes should be named using “CamelCase”—for example, DatabaseConnection. Class methods and properties should use lowerCamelCase, such as $lastStatement. The use of private class methods and properties should be avoided. You should define classes as protected so that another class can extend your class and change the method if necessary. Protected and public methods and properties should not use an underscore prefix.

All documentation files should have their file name extension set to .txt to make viewing them on Windows systems easier. Also the file names for such files should be in all caps (e.g., README.txt) while the extension itself should be in lowercase.

Checking Your Coding Style with Coder Module

At http://drupal.org/project/coder, you’ll find a treasure that will save you a lot of time and aggravation. It’s the coder module: a module that reviews the code in other modules.

To have the coder module review your module, click the new “Code review” link in your site navigation, and select the kind of review you want and the module or theme you would like to have reviewed. Or use the handy Code Review link that this module provides on the list of modules.

496

CHAPTER 22 ■ DEVELOPMENT BEST PRACTICES

■ Tip Use of the coder module should be considered mandatory if you are serious about getting up to speed with Drupal’s coding conventions.

You can even go a step further and use the coder_format.php script that comes with the coder module. The script actually fixes your code formatting errors. Here is how to have coder_format.php check the annotate module we wrote in Chapter 2:

$ cd sites/all/modules

$php contrib/coder/scripts/coder_format/coder_format.php \ custom/annotate/annotate.module

The script modifies the file annotate.module in place and saves the original as annotate.module.coder.orig. To see what the script did, use diff:

$ diff custom/annotate/annotate.module custom/annotate/annotate.module.coder.orig

Finding Your Way Around Code with grep

grep is a Unix command that searches through files looking for lines that match a supplied regular expression. If you’re a Windows user and would like to follow along with these examples, you can use grep by installing a precompiled version (see http://unxutils.sourceforge.net) or by installing the Cygwin environment (http://cygwin.com). Otherwise, you can just use the built-in search functionality of the operating system rather than grep.

grep is a handy tool when looking for the implementation of hooks within Drupal core, finding the place where error messages are being built, and so on. Let’s look at some examples of using grep from within the Drupal root directory:

$ grep -rl 'hook_init' .

./authorize.php

./includes/common.inc

./modules/simpletest/tests/system_test.module

./modules/simpletest/tests/theme_test.module

./modules/simpletest/tests/theme.test

./modules/simpletest/tests/actions_loop_test.module

./modules/locale/locale.module

./modules/dblog/dblog.module

./modules/update/update.module

./modules/system/system.api.php

./modules/system/system.module

./modules/overlay/overlay.install

./modules/overlay/overlay.module

./update.php

./themes/engines/phptemplate/phptemplate.engine

497

CHAPTER 22 ■ DEVELOPMENT BEST PRACTICES

In the preceding case, we are recursively searching (-r) our Drupal files for instances of hook_init starting at the current directory (.) and printing out the file names (-l) of the matching instances. Now look at this example:

$ grep -rn 'hook_init' .

./authorize.php:31: * avoid various unwanted operations, such as hook_init() and

./includes/common.inc:2697: * drupal_add_css() in a hook_init() implementation.

./includes/common.inc:2750: * theme .info files. Modules that add stylesheets within hook_init()

./includes/common.inc:3770: * drupal_add_css() in a hook_init() implementation.

./includes/common.inc:3810: * hook_init() implementations, or from other code that ensures that the

./includes/common.inc:4829: // Initialize $_GET['q'] prior to invoking hook_init().

./includes/common.inc:4835: // Prior to invoking hook_init(), initialize the theme (potentially a custom

./includes/common.inc:4837: // - Modules with hook_init() implementations that call theme() or

./modules/simpletest/tests/system_test.module:184: * Implements hook_init().

…

Here, we are recursively searching (-r) our Drupal files for instances of the string hook_init and printing out the actual lines and line numbers (-n) where they occur. We could further refine our search by piping results into another search. In the following example, we search for occurrences of the word poll in the previous example’s search result set:

$grep -rn 'hook_init' . | grep 'dblog'

./modules/dblog/dblog.module:88: * Implements hook_init().

Another way to refine your search is by using the -v flag for grep, which means “invert this match”; that is, let matches through that do not match the string. Let’s find all the occurrences of the word lock without matching the words block or Block:

$ grep -rn 'lock' . | grep -v '[B|b]lock'

./includes/common.inc:2548: // See if the semaphore is still locked.

./includes/database.mysql.inc:327:function db_lock_table($table) {

./includes/database.mysql.inc:332: * Unlock all locked tables.

...

Summary

After reading this chapter, you should be able to

•Code according to Drupal coding conventions.

•Document your code so that your comments can be reused by the API module.

•Comfortably search through Drupal’s code base using grep.

•Identify Drupal coding ninjas by their best practices.

498