Drupal is a powerful CMS right out of the box. But let's be honest. The real reason that Drupal has gained such traction in the crowded PHP CMS space isn't because it is loaded with bells and whistles, but because it can be extended in seemingly infinite ways through add-on modules. In fact, there are well over seven thousand modules available from Drupal.org. Why is it that Drupal enjoys such a wealth of user-contributed add-on code?

The answer is that Drupal's API (Application Programmer Interface) provides the golden combination of simplicity and power. Almost every phase of Drupal's page building process can be intercepted and the data modified. But powerful modules can still be written in just a few dozen lines of code.

In the next few pages we are going to create a module from scratch. We will build a module using the Block API – the system used to generate block content. The module we create in this article is going to provide a block that displays the number of members (user accounts) on the site.

This is how we will proceed:

1. We will create a new module directory
2. Then we will create a .info (dot-info) file to describe the module
3. From here, we will create our basic .module (dot-module) file and introduce Drupal programming
4. Next, we will create a couple of “block hooks” to define the behaviors of our new block
5. Using the administration interface, we will turn on our new module and enable the block

Prerequisites

For this article, it is assumed that you have the following:

• Basic PHP development knowledge
• A running Drupal 7 instance with admin access
• Access to the filesystem for your Drupal 7 instance
• A code editor or PHP IDE

To get started, you will need a working Drupal 7 instance that you can access as an administrator. You will also need to be able to create files and directories inside of that Drupal installation. The examples in this article are done on a standard install of Drupal 7.0 with no contributed modules.

Creating a Module

Typically, a Drupal module has at least these three pieces:

• A module directory that contains all module files
• An information file
• A module PHP code file

We will call our module membercount. In Drupal parlance, this name is called the machine name because it is the name Drupal (the machine) uses to reference the module.

Now that we have the machine name, we can create our module's directory. The default location for add-on modules is the sites/all/modules directory. In that directory, we will create a folder named with the module's machine name: membercount/.

Inside of this directory we will create two files. The first file, which we will see in the following section, will contain information about our module. The second one will contain the module's PHP source code.

The .info File

The first file in our module is the .info file. Drupal uses the .info file to determine details about the module, including whether the module can be installed and what other modules it depends upon. A .info file is always named with the machine name of the module, so our module must be named membercount.info.

The .info file contains a list of name/value pairs. This file isn't an ad hoc settings file where you can put any information that you wish. There are a dozen directives that can be placed inside of a module. We will be using only the few that are required.

The name directive is required in all .info files. Its purpose is to provide a human-readable name for the module.

The description directive should have a one-sentence description of what the module does.

The next directive, core, has a functional role. Drupal refers to this to make sure that the module can be installed. Attempting to install this module on a Drupal 6 system, for example, would generate an error.

All three of these directives are required.

To see all .info directives refer to http://drupal.org/node/542202.

Starting the .module File

The next file that we are going to create is the .module file, membercount.module. This file is automatically loaded by Drupal, which expects the file to contain PHP code. Like .info files, the base name of a .module file is the module's machine name.

For the most part, Drupal modules are written as procedural code. Typically, the preferred unit of organization for Drupal code is the function. Our module file will have a three functions in it. Here is the first:

There are a couple things that I will note in passing, but which we don't have the space to examine more closely.

The first is the <?php processor instruction. This is required for any PHP files. Note, however, that there is no closing ?>. This is not only legal in PHP, but is considered a best practice for a file that is entirely source code. It prevents errors caused by premature buffer flushes.

The second thing is that it follows a very strict set of coding conventions. These conventions, described at http://drupal.org/node/360052, cover everything from indent depth (two spaces, no tabs) to naming conventions (lowercase with underscores), operators (one space on each side), and comment styles. Drupal developers are expected to follow these conventions in order to maximize the readability across the codebase.

The next thing of note is the use of documentation blocks. Documentation blocks are a special kind of comment that begins with /** and ends with */. The purpose of these sections is to provide source code documentation that can be extracted by automated tools. Every PHP file should have a file-level documentation block (which is flagged with the @file tag). Each function should also have a documentation block.

Now we are ready to look at the function declared in the file above. The membercount_help() function provides help text for the module. By declaring this help function as above it is now available to Drupal. If we were to install the module as it is and go visit the help page, we would be able to see this help text under the Member Count module.

Drupal has picked up our help function and integrated it into its help system. How did it do this?

This is where Drupal's cornerstone feature comes into play. Drupal uses a callback-like system called hooks. At strategic times during page processing, Drupal looks for any functions that follow a specific naming pattern (hook functions) and it invokes all matching functions. For example, when generating help text Drupal looks for anything that implements hook_help(). It then executes all of the matching functions, gathers the returned data, and displays the requested help page. To implement hook_help(), all we need to do is declare a function where the hook part of the name is replaced with our module's machine name: membercount_help().

Declare a function according to a predefined hook pattern and Drupal will just pick it up and use it. This is why Drupal is so easy to extend.

Of course there is a little more to it then that. You need to know what each hook invocation will give as input, and what output your hook is expected to return. In our example above, hook_help() implementations will get two arguments:

• $path: The help path. A top level help screen will always get the path admin/help#MODULENAME.
• $arg: Additional arguments passed in the URL.

The hook will be executed for any call to the help system, so it is up to us to determine whether the help call is one that we should answer. That is why the body of our help function looks like this:

In short, we only answer this request for help if the $path is set to 'admin/help#membercount'. In a more complex module we might have an entire help system where different paths contained information about different parts of the system.

Any request to hook_help() expects one of two things to be returned: a NULL value or a string of help text. While NULLs are ignored, strings are prepared and displayed. In practice, modules should have informative help text, but for the sake of illustration we have kept ours very short.

Notice that the string isn't simply returned. It's passed through the t() function. The t() function is primarily for translating strings into non-English languages. But t() performs other tasks as well. It can be used to insert values into strings (like the sprintf() family of functions) and to do some output filtering before data is sent to the client. The t() function is documented at http://api.drupal.org/api/drupal/includes--bootstrap.inc/function/t/7.

Five other Drupal functions you ought to know

The article introduces several important Drupal functions. Here are a few other commonly used Drupal functions.

1. theme(): Pass data to the theme system for formatting
2. l(): Transform a label and URI into a link
3. module_invoke_all(): Execute a hook in all modules
4. drupal_set_message(): Print a notice or error to the user
5. watchdog(): Log a message to the Drupal log

Any string that contains output that is on its way to a user should be passed through the t() function. And this should happen when the string is declared. In other words, the following code is wrong:

$foo = 'This is my string.';
$bar = t($foo);

In order for the translation system to function correctly, t() should always be used like this:

$bar = t('This is my string.');

In the next section we are going to create a block.

Block Hooks

In Drupal, the block system is used for placing chunks of content around the periphery of the page. Blocks are administered through the Toolbar » Structure » Blocks page, where they can be positioned and configured.

Our module is going to provide a simple block that lists the number of accounts that exist on our site. To accomplish this, we are going to need to implement two hooks:

• hook_block_info(): Tell Drupal about the block that we declare.
• hook_block_view(): Answer a request to return a block's data.

There are other block hooks that we could implement, but for this example we can get by with just these two.

The first hook provides the information necessary to tell Drupal about all of the blocks that this module provides. Since our module only provides one block, our hook implementation is simple:

This hook provides the settings for each block that the module declares. The block info hook takes no parameters and returns an associative array where the keys are the machine names of each block, and the values are an associative array of settings for each block.

Our module declares one block called count_members. And we are assigning it two settings:

• info: This is required for every block. It should contain a short phrase describing the block. It is displayed only on block administration pages.
• cache: This second flag uses one of the DRUPAL_ cache constants to tell Drupal whether it can cache the data, and if so, how it should cache the data. These flags are all documented at http://api.drupal.org/api/drupal/modules--block--block.api.php/function/.... We assign it the value DRUPAL_NO_CACHE, which tells Drupal not to cache the output of this block.

There are a few other possible settings, but these two are the ones typically used.

Now that we have provided this hook our block will be included in the list of available blocks. Next, we need to provide the content that our block will return by implementing hook_block_view().

Just as the hook_block_info() function was expected to produce block information for all blocks that the module declares, hook_block_view() is expected to produce the viewable content for any block that this module is responsible for. Thus, our block hook only responds when the name passed into the function matches the name we declared in the $blocks array in membercount_block_info().

Inside of the if statement our block function does four things:

1. Query the database to find out how many users we have.
2. Format the string to be returned.
3. Create the block data structure (an associative array).
4. Return the block.

   Our database query is simple:

   SELECT COUNT(uid) - 1 FROM {users}

   This selects the number of user IDs (minus one) from the users table. The users table is the main location for information about Drupal users. There is one record for each user of the system, plus one for the "anonymous" user. Since we don't want to include the anonymous account in our tally we subtract one.

   When writing SELECT queries in Drupal, the syntax used is a slightly modified SQL. Notice that in Drupal queries, table names are always surrounded with curly braces ({}). This is so that on hosts that have stricter naming conventions, database table name prefixing can be done without requiring a manual rewrite of all SQL statements. These and other details of Drupal database syntax are documented here: http://api.drupal.org/api/drupal/includes--database--database.inc/group/....

   The database query is executed using the db_query() function. It executes a simple query and returns an instance of a DatabaseStatementInterface. Since our query returned only one field (the results of the SQL COUNT()) we can use the fetchField() method to get the data for that single field.

   The next line of our block function takes the $count value and uses it to construct a string for display:

   $content = format_plural($count, 'This site has 1 user.', 'This site has @count users.');

   This line shows another interesting facet of Drupal's translation subsystem. Along with t(), Drupal provides other functions to handle translation difficulties. Human languages construct plurals in different ways. The pattern used in English is not the same as that in French, Hungarian, or Chinese. So strings that need to be translated differently depending on a number can be passed through the format_plural() function. In the default English case it will see if the $count value is 1. If so, it will use the first string (This site has 1 user). Otherwise it will use the second (plural) construction, substituting $count for the placeholder @count.

   The next thing to do is construct the data structure that Drupal is expecting this function to return: an associative array with two keys:

   • subject: The title of the block, which may be shown to the user.
   • content: The formatted body of the block.

   For our block, we set the subject to Members (and we pass it through t() for translation). The content is simply the $content variable. For a more complex block, we might use the theme() function to theme the data before setting it here. Finally, we return the block, allowing Drupal to continue assembling the blocks and rendering the page.

   Installing and Configuring Our Module

   We now have a complete module. Since we created it in sites/all/modules, installing it is a breeze. We can simply navigate to Toolbar » Modules and find it in the list:

   

   Notice that the Name and Description columns pull their data from the membercount.info file we created earlier.

   Simply checking the box and clicking on the Save configuration button will enable our new module. It should then show up as enabled, and since we implemented hook_help(), we see a help icon in the right-hand column:

   

   Now we are ready to test out our module. Go to Toolbar » Structure » Blocks and position the block. Initially, there should be an entry named Count Members in the Disabled blocks list. We will put it in the Header section:

   

   Clicking Save blocks at the bottom of the page will save this change. Now we should be able to close the Administration overlay and see the results of our new block in the upper-right corner.

   

   Conclusion

   We have created our first working Drupal 7 module. At this point, you've gotten a small dose of coding in Drupal, though we have barely scratched the surface of what can be done. There is virtually no part of Drupal's page rendering that you can't modify through Drupal's APIs. And most of the time, modifying Drupal is just a matter of declaring a new module and writing the right hooks.

   The module we have created here is as basic as they come. More complex modules may contain multiple PHP source files, JavaScript files, and even templates, CSS, and images. It is even possible to group several modules together to create larger bundles of related features.

   Ready to move on? There are plenty of resources out there to help you get going, and Drupal.org is a great place to start.