Beginning Drupal Module Development or How I Wrote the Cacheflusher Module (Part 1)

Published June 17, 2011

This guest post was written by Ben Hosmer, a Drupal user new to module development as well as an active member of the Florida Drupal user community. He often blogs about Drupal related topics at radarearth.com

For the past five or six months, I've been itching to write a Drupal module. It seems to me to be the final step in attaining that Drupal nirvana, and you gain instant street cred as well at the monthly meet-ups. I've heard it also can up your certified to rock score too, since you get commits added to your history.

Thinking back to my early days learning Drupal, the mythical, magical, modules were those things you didn't mess with. You downloaded them, installed them, and usually they worked. The module developers were the big kids on the playground. The seniors in high school, so to speak. But, because of Drupal's awesome community, they weren't the bullies.

The CacheFlusher isn't my first module. I got my feet wet updating the Apture Module to Drupal 7, with some guidance from @ultimike (Mike Anello). Yeah, he is certifiied to rock a 7.

I learned a few things while I was updating the Apture Module, that made it a bit easier to write my own module from scratch.

What you need

First of all, you don't necessarily need to be a PHP guru to write a module. In fact, I am very far from it. You will need some basic, general understanding of programming flow though. I had dabbled in python before, and have been learning some PHP along the way too, but it definitely is not a pre-requisite. You just need a basic understanding of what code does.

You will need three things to write a module:

  1. A Drupal Installation
  2. A Text-Editor
  3. An internet connection (For references to the API)

You can set up a development environment on your local computer using WAMP if you are running windows, or MAMP if you are on the MAC. Linux folks, you most likely already have everything you need. Just make sure you are running PHP5.

Check out these getting started guides to help you get WAMP or MAMP if you don't already:

MAMP: http://www.mamp.info/en/documentation/index.html

WAMP: http://www.wampserver.com/en/

For an even easier setup with no installation, go to webenabled.com and sign up for a free account, although transferring files back and forth for testing might become tedious.

There are numerous text-editors available. A lot are free. Your operating system probably includes one. TextWrangler is my personal favorite for the mac, but you really need to try different ones to decide which one you really like. Windows users can use Notepad++. Some offer syntax and code completion as well as a lot of other nifty features.

Let's get started

The Modules Directory

First, if you have installed any contributed modules before, and you have ever peeked inside your sites/all/modules directory, you will see that there are a bunch of other directories with names like “views”, “mollom” and “colorbox”. These folders contain the code for each contributed module installed on your site. You will also notice that the names generally coincide with the name of the module. This is important, as we will soon learn.

Open one of the folders and look inside. I will promise you that you will see at least two files there along with possibly a README. One has a .info extension and the other has a .module extension, preceded by the exact same name of the parent directory.

The sites/all/modules folder

This is how Drupal keeps track of the contributed modules available when you visit admin/modules

If you plan on sharing your modules with the rest of the world, (really why wouldn't you), go set up git on drupal.org using the Git Instructions as your guide.

The .info File

After following the instructions, cd into your new module directory. You should see a .info file with your repository name already there. Drupal does this for you when you create your sandbox, and you just cloned it into your directory.

The Modules Directory

Open that .info file. This is kind of the table of contents for your module and contains some standard entries that every module should have.

What you will see is: name = yourmodulesname

This tells Drupal what the name of your module is. This is also where the information contained in the module overview page at admin/modules comes from.

We should add a few things before we are done here. Hit enter and start a new line.

Add description = a description about what your module does.

The .info File

This creates the description for your module on the module overview page.

Our next entry will tell Drupal where to categorize our module. When you view the module overview page at admin/modules you will see some headings for subcategories like “Core”, “Services”, and “Taxonomy”. This helps to keep your modules organized.

The Modules Overview Page

Add a new line and type package = administration

The last entry we will need is important so that Drupal knows what version of Drupal this module was created for.

Add core = 7.x

This tells Drupal that your module is for Drupal 7.

If you plan on sharing your module, don't add a “version” entry. Drupal will automatically do this for you when it is packaged.

Make a new line, and add your final entry, files[] = yourmoudlename.module

This directs Drupal to your actual module code so that it can run.

Save your .info file.

What the .info File will Finally Look Like

Here is what the final version of the CacheFlusher module's .info file looks like:

{syntaxhighlighter brush: php;fontsize: 100; first-line: 1; }name = CacheFlusher
description = Adds a quick way to flush your cache with a button on the admin toolbar.
package = "Administration"
core = 7.x

files[] = cacheflusher.module{/syntaxhighlighter}

If you start up your Drupal installation and go to admin/modules, you will see a new entry for your module on the module administration page. It won't actually do anything yet though.

The .module File

Next, you need to add your .module file. This is where all of the work gets done.

What are Drupal Modules?

Drupal modules are basically a series of functions, with a majority of them being function calls to Drupal functions. The documentation for every function available to Drupal can be found at api.drupal.org. This is your resource for finding out what each function does and how to use it.

As a newcomer, I found it to be lacking in examples. Sometimes it can be impossible to figure out what the function actually does. So, instead of complaining in a comment, I added some examples to the API entries.

 

After my frustration, I discovered the Examples Project that provides an excellent group of modules that do just what the project name implies--provide example modules for developers that give working code examples of what some of the popular functions actually do. It is an excellent resource and you should add it to your bookmarks toolbar because you will probably refer to it quite often.

 

You may find it very helpful to find a module that is very simple, and look through the code. If you are adding a menu entry for example, find a module that does the same thing and look through the .module file. 

 

Often you might find .inc files. These point to additional code that wasn't included in the .module file. These will be noted in the .module file though with a filename.inc. This references those additional files.

 

Another good resource is your Drupal installation itself. By browsing to the core modules folder found at /modules, you can search for the function you are looking for by using spotlight if you are using a mac, or search for windows or locate from your nix terminal.

 

This can often shed some light on the function or at least reveal what function to implement to perform a certain task.

Now that you have your .info file and your directory. You are ready to create your .module file and spin some code up.

View Your Module in Action

You can actually now got to your Modules page through your Drupal interface, and see the new entry for your module:

The Modules Administration Page

The second part of this article will go through the creation of your actual .module file.

Comments

I hate to be the bearer of bad news, but Cacheflusher module is a security vulnerability. Here's how it works:

1) I go to yoursite.com/sites/all/modules/cacheflusher/README.txt to confirm that cacheflusher is installed.
2) I create a webpage with an img tag that has src="http://yoursite.com/admin/cacheflusher" (I can't create an image tag in this comment - the text filter will strip it out - for security reasons).
3) I send you an email that says "Hi Ben, Come check out my cool Drupal site at http://mysite.com/page_with_the_fake_img_tag
4) You come visit my page, the cache on your site gets cleared.
5) I could litter these fake img tags on other pages that I know that you frequent.
6) Your site gets really slow and uses a lot of server resources because the cache keeps getting needlessly cleared.

The technical term for this is a Cross-site request forgery or CSRF.

To get around this see confirm_form()
http://api.drupal.org/api/drupal/modules--system--system.module/functio…

cheers

[...] Beginning Drupal Module Development or How I Wrote the …Description : Join Ryan Price, Mike Anello and special guest Matt Butcher – one of the co-authors of "Drupal 7 Module Development" as they discuss the book, the growing complexity of Drupal code, new modules, DrupalCon 2013 (Go Canada! … DrupalEasy is by far on of the best ways to learn Drupal; Mike & Ryan completely immerse you into the complex world that is Drupal. Their easy to understand teaching technique and approach to explaining site administration, …http://drupaleasy.com/blogs/bh .. [...]

Awesome! A must read for those who wish to know how to start module development for drupal

Submitted by nikkubhai (not verified) on Mon, 06/20/2011 - 07:22

Thank you. I'm glad you liked it and found it useful.

Submitted by Guest (not verified) on Mon, 06/20/2011 - 16:43

Thanks for pointing this out. I suppose I should have added somewhere that this shouldn't be used on a production site. I have this disclaimer in the project's page though, so if anyone does clone it hopefully they will be aware of it. I'll see what I can do about fixing this security issue.

Submitted by Guest (not verified) on Tue, 06/21/2011 - 04:18

Nice intro... when do we get part 2, showing how you actually wrote the module, not just the info file?

Submitted by Andy (not verified) on Tue, 08/23/2011 - 16:26

"I hate to be the bearer of bad news, but Cacheflusher module is a security vulnerability. Here's how it works:.."

Has this issue been fixed?

Bilal

Submitted by Bilal (not verified) on Mon, 11/14/2011 - 02:35

Sign up to receive email notifications of whenever we publish a new blog post or quicktip!

Name
CAPTCHA