Since Roles and Capabilities are introduced in WordPress 2.0, the User Level approach has been declared deprecated. However, it’s disappointing that a lot of plugins and themes out there still use user levels to control access to admin option pages and other functionalities. This guide shows you how to properly use Roles and Capabilities in your plugins and themes.

Note: This article is a long one, therefore you should probably bookmark it so that you can always come back later for reference.

Table of Contents

  1. What are Roles and Capabilities?
  2. Capabilities and administration menus
  3. Checking a user’s capability
  4. Adding custom user roles
  5. Adding custom user capabilities
  6. WordPress Capability Classes

What are Roles and Capabilities?

As in other CMS and web applications, WordPress has a built-in system to verify whether a particular user has enough privilege to take a certain action. Users are divided into Roles, and each Role is assigned certain capabilities (or permissions). Here is a summary of WordPress default roles:

Administrator – Somebody who has access to all the administration features

Editor – Somebody who can publish posts, manage posts as well as manage other people’s posts, etc.

Author – Somebody who can publish and manage their own posts

Contributor – Somebody who can write and manage their posts but not publish posts

Subscriber – Somebody who can read comments/comment/receive news letters, etc.

This system of Roles and Capabilities is much more flexible than User Level, since it enables you to add, remove or reassign capabilities among roles. You can even add more roles to the system without destroying the default setup.

Capabilities and administration menus

Almost every plugin needs to have at least one page in the admin area to let users customize how the plugin is used. In order to do this, you need to add your own administration menu items. There are a bunch of WordPress functions which let you do this:

As you can see, there’s always a required parameter called capability for each of those functions. This essentially means the user who logs in to the administration area needs to have a certain capability to see the menu item. You can either use a user level (which is deprecated and not recommended), or a string representing a certain capability (for example, edit_posts).

Many plugins still use user levels (numeric representation of a user’s privilege, from 0 to 10). However, this is deprecated and should not be used anymore. By using capabilities, you won’t have to worry when user levels are not supported by WordPress, and if you want to add and use your custom capabilities, this is the way to go.

If you use the functions above to add menu items to the admin area, only the users who have the specified capability can see the menu items and access the pages associated with those items. If your theme or plugin has an option page, it’s important that you restrict access to that page properly. For example, if it’s a theme option page, you should use edit_themes capability, while if it’s a plugin option, edit_plugins. Another way is to use manage_options for both plugin and theme option pages.

Remember, sometimes the blog administrator wants to share and divide responsibilities among several other users. As a result, using capabilities make your themes and plugins much more customizable.

Checking a user’s capability

If your plugin or theme involves the user making changes to the blog’s data (adding new or editing existing content etc.), it’s very important that you check whether the current user has enough capability to make a certain action. The current_user_can() function lets you do this:

This function also accepts an optional argument for a certain post ID, in case you want to check whether the current user can do something to that post:

There’s another function you can use to check whether the author of a certain post has a certain capability:

The first argument can be either a post object, or a post ID. Although this function is rarely used, it’s helpful to know it’s there. I personally never had to use that function, but if you have an interesting example, let me know in the comment!

Adding custom user roles

Sometimes it’s necessary for your plugin to add new roles to the system. Let’s say you’re coding a new gallery plugin where users can register to upload photos to your site, but that’s it – these registered users can’t add or modify any other type of content to your blog (such as posts or pages). The best way to do this, is to add a new custom role:

What this function does is add a new role to the system with a set of capabilities. The example aboves add a role called “photo_uploader”, with a display name and an array containing a list of default capabilities for that role (in this case, organize_gallery ).

When you process a request to create, edit or upload galleries, you should use current_user_can() to check whether the current user are permitted to take these actions.

The users who are assigned this role can only organize_gallery, but cannot edit_posts or publish_posts.

To remove a role, you can use remove_role():

You should have an option somewhere for your plugin users to remove this custom role when they decide to uninstall your plugin.

But what if you want to add capabilities to existing users?

Adding custom user capabilities

This is useful when you develop a plugin that allows users to take actions other than manipulating post contents. Let’s come back to our gallery plugin example above. Say, if you also want to assign organize_gallery capability to existing roles (administrator, editor, author, contributor etc. ), what would you do?

WordPress Capability Classes

We’ve covered checking and adding capabilities, as well as adding roles. These are the most frequent used functions for managing user permissions in WordPress. However, as the title of this post contains the word “ultimate”, I’d like to also cover the three WordPress classes that work behind the scene and the API these classes provide, which you can use for advanced permission management in your plugin. These three classes are:

  • WP_Roles
  • WP_Role
  • WP_User

The source code of these three classes can be found in wp-includes/capabilities.php. The source code is documented in great details and I’m sure you can understand it easily, but I’d like to sum up what you can do with these classes.

The WP_Roles Class

This class, as its name suggests, is for managing roles in general. When you use it in your plugin, you actually don’t have to initiate a new object, but use a global object which has been created by WordPress:

The $wp_roles is available as a global object, and can be used anywhere in your functions, as long as it’s declared beforehand in your functions with the global keyword.

As covered before, you can add and remove roles using add_role() and remove_role(). These functions are actually wrappers for $wp_roles->add_role(), and $wp_roles->remove_role. Therefore you can add and remove roles using the $wp_roles object as well:

Likewise, you can also get a role using this method:

You can also get a list of available roles, containing pair of role names and role display names. This is useful when you want to provide an interface for the user to change capability assignment.

Finally, you can add and remove capabilities using $wp_roles too, making this object versatile for almost all roles and capabilities operations.

WP_Role Class

This is a very simple class. All it does is adding and removing capabilities.

WP_User class

This class lets you manage roles and capabilities per user, which means you can assign multiple roles to a particular user, or add a capability to a certain user regardless of his current role.

First of all, you need to get the user object before manipulating its roles and capabilities:

As you can see, you can get a user object based on either his user ID or username. With the latter, the first parameter must be empty (either null or an empty string). Examples:

Once you have the user object, you can add another role to this user without modifying his current role (which means the user can have as many roles as you want):

Or you can remove a role from this user, using remove_role():

You can also set a role to this user, which means removing all the current roles of this user and assign a new one:

For manipulating capabilities, you have a bunch of methods that allow you to do various things:

Conclusion

There, that’s all there is to know about Roles and Capabilities. You might not need to grasp all of this, but it’s definitely helpful to know WordPress has a full-fledged user and role management system, which you can always use for complicated projects. This post has been all theory so far, but in the next tutorial, I’ll show you how to use this knowledge to build a “client login” area for your WordPress portfolio site.

If you have any comment or suggestion, please leave it below!