Home / Comment permalink

Everything you need to know about naming your Drupal contributed project

So you're contributing a module or theme to the greater Drupal community. Awesome! We're thrilled that you're sharing your work.

Naming your project may be one of the last things on your mind, but a poor naming choice could cause you issues down the road. Your project name ends up in a lot of places, including: Google Search Results, Drupal.org related project listings, the URL to the project, the title of your project page, Drush commands, the filenames of your project files, hook invocations in your project, and CSS classes, to name a few. A name that's used inconsistently can be confusing for users and cause integration issues.

There are several principles to consider and some are more important than others, so I've broken them into three categories: The Essentials, Strong Recommendations, and Further Suggestions.

The Essentials

Some project names are just not possible due to technical limitations of our tools and naming conventions. These rules are considered "essential" because if you break them, you'll break your site.

1. Make sure your project name is unique

This may be fairly obvious, but you cannot contribute a project that has the same name as an already existing project. Drupal.org will not accept two projects with the same project URL (and your URL should match your module name — more on that in a moment). While it's technically possible to release a duplicate module name under a different project URL, or on a completely different host (like Github), you'll be setting yourself up for failure since those two modules cannot be used concurrently without site-breaking namespace collisions. To see if a name has been claimed, try out the name in the project URL: http://drupal.org/project/{name}. If a project page already exists at that path, the name has been claimed; if not, it's yours for the taking.

2. Don't use a name that conflicts with Unix filename rules or PHP function naming conventions

Your project machine name is used in the project folder and filenames, so it must be a valid Unix filename. With Drupal's hook system, your name also winds up as part of PHP function names. If anything in your name doesn't follow PHP function naming conventions, it will cause Drupal to throw errors or not recognize your module/theme. A few things you'll want to avoid are:

  • Names starting with a number
  • Hyphens in the name
  • Spaces in the name
  • Names containing double underscores (__)
  • Special characters

I know, I know, you've been dying to use that Unicode Skull and Crossbones somewhere (Rock On!!! ☠). Better to save it for something else.

Strong Recommendations

Some project names are technically possible but are really not recommended. The wrong name can lead to issues integrating with other tools, conflicts with other modules, and confusion among users.

3. Avoid underscores in your project name

Several sources, including John VanDyk's "Pro Drupal Development" recommend against using underscores in your project name. It's possible to use underscores and have no issues, but the nature of the hook system and Drupal function naming means that each underscore you use takes up an additional namespace. This creates a risk of conflicting with current or future similarly named modules.

You especially want to avoid an underscored name starting with the name of an active core or contrib module. For example, if you made a module named "views_preprocess," you would unknowingly create a conflict with the views module, because it defines a function called views_preprocess_comment(). By enabling your module, this otherwise unassuming function magically becomes an implementation of hook_comment(), resulting in broken code or other unexpected consequences.

Instead of using underscores, the standing recommendation is that you simply combine multiple words together (like "addanother," the machine name for the Add Another module). Some developers prefer this naming as a matter of coding style, since it encourages short module module names and separates the name visually from the rest of the hook invocation (think addanother_form_alter instead of add_another_form_alter). However, it may come with a readability cost (do you find the name "thisisanewmodule" difficult to read?).

4. Make sure your Drupal.org project URL matches your project name

If your project URL doesn't match your project's machine name (which is used in the project filenames and hook invocations), then automation tools like Drush or Make cannot download your project from Drupal.org. This prevents people from using it in build scripts or packaged distributions. Specifically, you might be tempted to separate words in project URL with hyphens, as is typically done in URLs. If you make this mistake (like I did) the only solution is to deprecate your project on drupal.org and start it up again at a new URL, which can be pretty inconvenient. Note: There is an open issue in the drupal.org customizations queue to prevent people from making project URLs with hyphens or other disallowed patterns. Jump in, if you want to prevent issues like these in the future.

Further Suggestions

The following rules are simply suggestions. You probably won't break things if you don't follow them, but you can prevent confusion if you do, and that's always good.

5. Keep the project name short

Long names don't work very well in some contexts, like filenames which have length restrictions on many systems. Long machine names impair code readability since camelcasing or separating words with underscores is discouraged. Plus, who wants to type out a long name every time they are trying to search for your module, or style your CSS classes? Short names are easier for humans to read, type, say, and remember.

6. Choose a name that describes what your project does

This is admittedly subjective but there is definitely a pattern in the Drupal community. Drupal module names tend to be very practical. The Block Class module, lets you add classes to Blocks. The Clientside Validation module, adds clientside form validation to webforms. The SEO Checklist module is, you guessed it, a SEO Checklist. This makes modules findable. For example, If people are searching online for a module to add classes to blocks, they're more likely to find the right module if it's named "Block Class." We want them to imagine functionality, guess what it might be named, find the module matching that name, and discover that it solves their functional issue. My opinion is that theme names don't need to be as descriptive, but they ought to at least make sense. The name "Tigerlilly" may be a fine theme name, but it probably doesn't make a good module name.

7. Choose a name with sufficient mental distance from other project names

If your module name is too similar to another module name, users are going to mix them up. You may end up getting issues in your queue for the wrong module or support requests from people who think you maintain the other one. You don't need to think too hard about this… if there's a module named "Token" don't name yours "Tokin", "Tokens", or other similar derivatives.

8. Use the same name everywhere!

I touched on this with the project URL, but it goes for anywhere you use your project name. Use the same name on the title of your project page, in your documentation, in your .info file, in your commit messages, in your CSS classes, in your blog posts... use the same name everywhere! We want our naming to be consistent across technical contexts but we also want it to be consistent in the minds and expectations of our users.

That's a lot of Caveats

If you're like me, you're probably thinking, "So let me get this straight. I can't use one of the 14,000+ names already claimed (or anything too similar to them), which really limits my options. And multi-word names are troubling because I can't use spaces, hyphens, or underscores between words, which make them difficult to read and hurts SEO on my project page. Isn't just naming things hard enough?" Yes, you're right. Drupal's large module ecosystem and the various ways to integrate them results in some naming constraints. When in doubt, look at how the core modules are named or browse through contrib and follow the examples you see. That will get you most of the way to where you need to go.


Posted on by David Corbacho Roman (not verified).

Nice tips and hat off for recognizing your mistake.
Choosing a good module name is difficult indeed, but makes your life easier in the long run.

And use your name everywhere. True. Avoid stuff like in D6 "drush dl cck" / "drush en content"

Add new comment

Plain text

  • No HTML tags allowed.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Lines and paragraphs break automatically.

Filtered HTML

  • Use [acphone_sales], [acphone_sales_text], [acphone_support], [acphone_international], [acphone_devcloud], [acphone_extra1] and [acphone_extra2] as placeholders for Acquia phone numbers. Add class "acquia-phones-link" to wrapper element to make number a link.
  • To post pieces of code, surround them with <code>...</code> tags. For PHP code, you can use <?php ... ?>, which will also colour it based on syntax.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Allowed HTML tags: <a> <em> <strong> <cite> <blockquote> <code> <ul> <ol> <li> <h4> <h5> <h2> <img>
  • Lines and paragraphs break automatically.
By submitting this form, you accept the Mollom privacy policy.