Last updated October 25, 2012. Created by RobLoach on January 5, 2008.
Edited by drupalshrek, fullerja, LeeHunter, jhodgdon. Log in to edit this page.

Main topic described: Permissions
Drupal hook described: hook_perm

The main module file

The main module file will be called [your_module_name].module. It is important that it has that name, since that is what Drupal will look for. If you just call it something like [your_module_name].php then Drupal will not find it as and treat it as a module. The [your_module_name].module file will contain the heart of your module code, including the permissions code which we describe on the rest of this page. Your module will therefore always begin with the following 2 files:

  • [your_module_name].info
  • [your_module_name].module

Defining permissions

The next function to write is the permissions function, implementing Drupal's hook_perm(). This is where you will define the names of the permissions of your module -- it doesn't grant permission or define what the permissions mean, it just specifies what permissions are available for this module. As with the help hook from the previous tutorial page, we implement hook_perm() by creating a function called onthisdate_perm() in the onthisdate.module file. This function just needs to return a list of the permission names this module will use; once you have defined permissions in the hook_perm() implementation in a module, an administrator can define which roles have those permissions on the Administer » User management » Permissions page.

For example, in order to create a single permission called "access onthisdate content", we would create the following function:

<?php
/**
* Valid permissions for this module
* @return array An array of valid permissions for the onthisdate module
*/
function onthisdate_perm() {
  return array(
'access onthisdate content');
}
// function onthisdate_perm()
?>

(Note for beginners: the opening <?php will only appear once in your module file, at the beginning, and the closing ?> will not appear in your file at all.)

If you are going to write a module that needs to have finer control over the permissions, you can expand this permission set. For example:

<?php
return array('access onthisdate content', 'administer onthisdate');
?>

For this tutorial, start with just the one permission. We'll later expand to using additional permissions.

Your permission strings are arbitrary, but each must be unique among all installed modules. Otherwise, one occurrence of the name will take the permissions of the other. For that reason, the permission strings should each usually contain your module name, since this helps avoid name space conflicts with other modules. The suggested naming convention for permissions is "action_verb modulename". Use the following example as a template for any module you may be developing:

<?php
function newmodule_perm() {
  return array(
'access newmodule', 'create newmodule', 'administer newmodule');
}
// function newmodule_perm
?>

See Also

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.

Comments

I just want my module open to all, whenever it's enabled.
Do I have to add a perm function?

No, you don't have to have a perm function. It specifies permissions that you then have to check in your module logic if you want to allow/disallow certain things based on them.

No, you don't have to have a perm function. It specifies permissions that you then have to check in your module logic if you want to allow/disallow certain things based on them.