4.4. Checking Permission: user_access and Friends

Now that you've created a permission, how do you actually make sure that it is respected in different actions? The major function is user_access(), and it can be called with just one parameter, as in this simple example:

if (user_access('some permission')) {
  // Code that should only run if the current user has "some permission"
}

The function checks to see if the current user has that permission and returns either TRUE if he does or FALSE if he does not have the permission. In this first example, it is called with just one parameter: the name of the permission to check. It's also possible to call it for a specific user to see if that user has access to do something. An example of this second variation on user_access() can be seen in the function user_access:

if (user_access('administer nodes', $account)) {
    return TRUE;
  }

In this case, the user account identified for the node_access function is tested to see if it has the permission "administer nodes," because that permission grants a user access to all content on a site.

A third very common example of using user_access comes from the hook_menu definition.

4.4.1. Menu Callback Permissions

One of the most common places to check a user's access is in the menu definition. Drupal's menu system is based on each module implementing the hook_menu function, which returns an array filled with information about the menus and paths defined by that module. The array has two keys that are related to access: access callback and access arguments.

Following is a single item from the hook_menu implementation in the Blog module:

$items['blog'] = array(
    'title' => 'Blogs',
    'page callback' => 'blog_page_last',
    'access arguments' => array('access content'),
    'type' => MENU_SUGGESTED_ITEM,
    'file' => 'blog.pages.inc',
  );

In this code, the path for blog is defined to have a title of Blogs, and the content will be created by the page callback function blog_page_last. It will be a "suggested" menu item that an admin can enable, and whenever the page is accessed Drupal will be sure to include the file blog.pages.inc prior to running any code. The access arguments element to the array is the most interesting to us now. This example uses some shorthand by omitting the access callback function, which indicates to the menu system that it should use the user_access function to evaluate the arguments. The arguments, an array of permissions, are passed to the user_access function, and the return value is checked to determine if it is true. In this case there is just one permission to check. Further elements in the access arguments array are used only with custom access callback functions.

An array item from hook_menu can also define its own function to check access. Here is another snippet of code from the Blog module:

$items['blog/%user_uid_optional'] = array(
    'title' => 'My blog',
    'page callback' => 'blog_page_user',
    'page arguments' => array(1),
    'access callback' => 'blog_page_user_access',
    'access arguments' => array(1),
    'file' => 'blog.pages.inc',
  );

This example uses both of the array keys for access control. By specifying an access callback, the module is able to use more advanced rules to determine access beyond what is available from the default user_access test.

The menu system has several special processing rules. This example from the Blog module shows two of those special rules:

• The %user_uid_optional is a wildcard menu path that, if a number is the second part of the path, will load the user that corresponds to that user ID number.

• The array(1) value for the access arguments means that the access callback will be passed whatever is in position 1 of the URL. Counting of positions is zero indexed, so position 1 is the second item in the URL, which is the user object in this case.

Let's look at an example. When a visitor enters blog/2, the menu system will confirm that the user is able to view that by first loading the user object for user 2 and then passing that user object to the function blog_page_user_access. Now the code for blog_page_user_access:

function blog_page_user_access($account) {
  return $account->uid && user_access('access content') &&
(user_access('create blog entries', $account) ||
_blog_post_exists($account));

}

This code does several checks all on one line:

• It confirms that the account loaded by the wildcard loader exists by confirming the $account->uid is an actual user ID and not the ID for anonymous users:0. Drupal has a restriction that only users with actual account numbers can maintain blogs.

• It makes sure that the present user—the user looking at the page—has the general permission to access content.

• It makes sure that either the uid for this blog has the ability to write blog posts or, by calling _blog_post_exists(), that uid no longer has that ability but created some blog posts in the past, which are currently published.

This is just one example of how menu wildcard loaders, access callbacks, and access arguments work. There are many more examples, but they are all based on the same rules as these two examples.

4.4.2. Input Format Access: filter_access

The Filter module contains its own security system apart from the normal user_access system. It is fairly likely that this will be changed in the future so that filters are just normal permissions controlled by hook_perm and user_access. For now, we need a separate check.

Figure 4-1 shows the filter system's nonstandard set of controls for determining which role can use a filter. It also provides a function to check if a user has permission to use a particular format: filter_access. The filter_access function takes only a single parameter, which is an integer for the ID number of the filter. It checks access for the current user.

Figure 4.1. Permission control for the Full HTML input format

This function is not particularly common. It is used almost exclusively in Drupal core Block, Node, and Filter modules. However, it is a good function to know about if you ever need to check what kinds of input formats a user should be able to use.