A Very Quick Introduction to Drupal's hook_permission() and hook_perm()

Disclaimer: This post describes how to create a custom module and use it to create custom permissions on your drupal site. The purpose is to present a general idea of how to implement hook_permission() (or hook_perm() if using drupal 6) to create custom permissions, as well as to use and find drupal hooks. This tutorial assumes you know how to create and upload files to your server using FTP.

NOTE: Though we will not need it for the purposes of this tutorial, knowledge of the usage and implementation of the devel module may be useful as you continue your exploration of custom drupal modules.

1. Creating a module

First, let's make a new module. Follow these steps exactly.

  1. Create/Upload a new folder in you drupal's sites/all/modules/ folder named custom_example
  2. Create/Upload two new files in that folder: the first named custom_example.info, and the second named custom_example.module
  3. Take a moment to notice that the module's folder name and file names are the same.

Now edit the custom_example.info file, and make it's contents the following:

name = Custom Example description = Just a simple example module version = 0.1 core = 7.x package = Alpha Custom Modules

Save/Upload that file.
Drupal 6 note: If you're doing this in drupal 6, change the 'core' number to 6.x

Next, edit the custom_example.module file and make it's contents the follow:

<?php

Thats it! Save/Upload that file and then visit your site's module page.

On your site's module page, you should now be able to see and enable the module (it's in the "Alpha Custom Modules" section). Do so.

2. Creating a hook

Hooks in drupal are just ways of modifying the website page's results.
Let's create one in our new module.

Though there are two hooks being explored in this tutorial ( hook_permission and hook_perm ), you will only need to use one of them. If your site is a drupal 7 site, you will be using hook_permission(). If your site is a drupal 6 site, you will be using hook_perm(). These links will take you to the drupal api pages that describe each hook in detail.

2.a. Using hook_permission() in Drupal 7

In drupal 7, let's edit the custom_example.module, and make its contents the following: <?php /* * Implementation of hook_permission() */ function custom_example_permission(){ }

2.b. Using hook_perm() in Drupal 6

If you are instead using drupal 6, make your module contents the following: <?php /* * Implementation of hook_perm() */ function custom_example_perm(){ }

Now here is the important part about using a hook:
Copy the hook function from drupal's API page, and replace the word hook with your module's name.
Your module is now "hook"ed into drupal's menu system.

3. Creating the custom permission

Again, if you are using drupal 7, edit the module to the following: <?php function custom_example_permission() { return array( 'administer my module' => array( 'title' => t('Administer my module'), 'description' => t('Perform administration tasks for my module.'), ), ); }

In drupal 6, it's actually much simpler code. All you need to have in your module is the following: <?php function custom_example_perm() { return array('Administer my module'); }

Save before continuing (always save your work!), and now let's look at what we've done here (Notice 2 things: 1 - In drupal 7, the strings are wrapped in the t() function; and 2 - In drupal 6, there is no description, there is simply the permission name):

  • 'title' => t('Administer my module'): This key-value pair creates the name of the permission that is displayed on your site's permission page.
  • 'description' => t('Perform administration tasks for my module.'): This simply gives a description of what the permission does.

If you visit the hook_permission api page, you will notice there are more options available in drupal 7, but those are optional, and the two above are all that is needed for this introductory tutorial. Feel free to explore those on your site and try them out, you may find them useful.

Now you will be able to call these permissions using the user_access() function. For example, if you would like to restrict access to a part of your site with this permission, you would do something like this: <?php if (user_access('Administer my module')) { // you have access! } else { // no access. }

And that's it! This is all that is required to create new custom permissions on your drupal site.