Roles have been an integral part of WordPress for quite some time now — many functions associated with managing them have been in place since version 2.0.0. Despite this longevity, they are rarely utilized which is a shame since they allow for the easy setup of custom user types (and also have the ability to micro-manage them). In this article, you’ll learn everything you need to utilize user roles in WordPress and make the most of this incredible built-in functionality.

Terminology

The main terms to know are “role” and “capability”. Capabilities are the core of the system, they represent the things you can do. An example of a capability is switch_themes. A user who has this capability is able to change the look of the website using the Appearances section in the admin. Those who do not have this capability will not be able to do so.

Roles are simply a named set of capabilities. Imagine you have capabilities like edit_post, add_user and so on. Instead of listing all 50 of them for each and every user who you’d like to be an admin, simply assign each user the “admin” role and then assign all the capabilities to that role.

The Default Setup

By default, WordPress has six roles and about 57 capabilities. Each role has a different combination of capabilities which endow the user with the appropriate rights and privileges.

For example, a contributor can edit and delete his own posts, but cannot control when these posts are published (and cannot delete those posts once they are published). This is because they have the edit_posts and delete_posts capabilities, but they do not have the publish_post and delete_published_post capabilities.

The default setup3 offered by WordPress is very well thought out and should not be modified, only added to. If it is changed, you could face difficult problems later on — like a contributor being able to remove posts from your website, or an admin not being able to change the theme.

When New Roles And Capabilities Are Needed

New roles usually come hand-in-hand with new capabilities. Usually, we first create a set of new capabilities, which are held by the admin (and a new role, as well). Let’s look at an example.

If you have a large website, chances are you have a marketing team. This team doesn’t need to be able to edit and publish posts, but they do need access to advertising stats, trending search topics, etc. Perhaps it would also be beneficial to allow them to manage categories and comments for SEO purposes and customer satisfaction, respectively.

Our first order of business is to look at the advertising stats and trending searches. This is not something WordPress offers by default, so let’s presume it has been built as a plugin. Let’s create a capability called view_stats. This will be given to the marketing people and of course to the admin. Other users — like editors and authors — do not need to see the stats (which, in many case, is sensitive data) so they will not receive this capability.

Our second task is to decide what other capabilities our marketing people need. Based on our assumptions above, they will need the read, manage_links, manage_categories and moderate_comments capabilities.

Lastly, we would use some coding chops to create a new role named “Marketing”, and assign the above-mentioned capabilities to it. Once that has been done, we are able to appoint the “Marketing” role to any user within the “Add User” and “Edit Profile” page.

Basic WordPress Functions

To manage roles and capabilities effectively, all you need is five very straightforward functions:

add_role() — Enables you to add a custom role

remove_role() — Enables you to remove a custom role

add_cap() — Enables you to add a custom capability to a role

remove_cap() — Enables you to remove a custom capability from a role

get_role() — Gets information about a role as well as associated capabilities

If you would like to view the documentation for these functions, you can take a look at the Roles and Capabilities4 section in the Codex.

Implementing New Roles And Capabilities

The full implementation of roles and capabilities requires more than just the five functions I mentioned. We’ll also need to use functions for checking capabilities, we’ll need features which are only available to certain roles, and so on.

The function above will add our new “Marketing” role. It adds four capabilities which are already included in WordPress and a fifth one which is a custom capability. As you can see, no special coding is required to add custom caps — just include them in the array when adding the role. Once we add the new role, we make sure to add our new capability to the admin role as well.

Note that the add_role() fuction returns a WP_Role object on success or NULL if the role already exists.

Since the above code will be used in a plugin, the best way to use it is to utilize hooks, and to add the capabilities to the administrator only when we first create the role.

The code above will add a top level menu to the admin area for our marketing stats page. The add_menu_page() function allows you to specify a capability (the third argument) which determines whether or not the menu is shown.

Note that even though the add_menu_page() function itself takes the capability as an argument, we still need to check for it in the function which displays the content of the page.

This leads us into our next two functions nicely: current_user_can() and user_can().

If you want to check whether or not the currently logged-in user has a specific capability, simply use the following format:

if( current_user_can( 'any_capability' ) ) {
// The user has the capability
}
else {
// The user does not have the capability
}

If you would like to check whether or not an arbitrary user has a specific capability, use the user_can() function:

if( user_can( 45, 'any_capability' ) ) {
// The user with the ID of 45 has the capability
}
else {
// The user with the ID of 45 does not have the capability
}

In addition to capabilities, both functions can check for roles as well:

if( current_user_can( 'marketing' ) ) {
// The current user is a marketing person
}
else {
// The current user is not a marketing person
}

Creating User Types

While not an official term, I call different roles “user types” when they require many different front-end changes. Say you’re building a theme marketplace, for example. Apart from the administrator who oversees all (and the authors who would write in the company blog) you also have buyers and sellers. These are both registered users of your website but would require somewhat differing front-ends.

The profile page of a buyer would most likely show the number of things he’s bought, how frequently he buys stuff and when logged in, he would see a list of downloads.

A seller’s profile would be a portfolio of his work, his most popular items, and so on. When logged in he should probably see sales statistics.

Figuring Out Roles and Permissions

To make things simple, users either buy or sell, and cannot do both. Let’s create the two roles with a set of capabilities (off the top of my head…):

The idea here is that sellers are like authors, who will store sellable items as posts. Therefore, they receive the capabilities of an author. In addition, they can also view sales stats for their own items.

In addition to viewing items, buyers can also add payments and download files related to items that they buy.

Admins receive all these permissions, but in addition, they may view the statistics of any other user, add payments to any account, and may download resources for any item.

Frontend Implementation

From here on out it’s a matter of using our role and capability checking functions to determine who sees what. Let’s take a look at a couple of examples:

Listing Users

If we list all the users on the website, we could show the items bought for the buyers and the items sold for the sellers. Here’s how:

Most of this is plain old HTML, but the important thing to take away is how the counter is created. Note that the get_purchases_count() and get_sales_count() functions are fictitious (they are not part of WordPress, of course).

Of course, in a real world example we would need to make sure that only buyers and sellers are listed, and we might need to create a separate template for them completely (if the differences are numerous enough).

Hallo, my name is Daniel :) I build plugins, themes and apps - then proceed to write or talk about them. I'm the editor for the WordPress section here on Smashing Magazine and I contribute to various other online sites. When not coding or writing you'll find me playing board games or running with my dog. Drop me a line on Twitter or visit my personal website.

Daniel Pataki

I’m sorry it wasn’t exactly up your alley! I see where you’re coming from though and the answer is yes, you’ll need a plugin to create and manage roles if you’re not familiar with programming. There are a few out there, I think Role Scoper is pretty good, but please read some reviews before you try it :)

Jeff

Melindrea

Nice and useful article, though you have a minor mispelling here: “both fucntions can check for roles”

Do you know of a way to easily extend one of the current roles, IE if I want a role to be “Contributor, with these added permissions”, do I need to look through the different permissions for Contributor, or is there a way to handle it better? Or in that case, am I best off giving Contributor those permissions?

-1

5

Daniel Pataki

I recommend going through permissions individually unless you really know everything well – just in case you add a permission you don’t want to. If you want to copy capabilities from a role the first thing that comes to mind is something like this:

If you look at the code snippet under “Figuring out roles and permissions”, replace lines 30-33 with the following:

Pierre Saikali

I’m always impressed by the number of (useful) functions WordPress has, and even after a couple of years developing with this platform, I’m learning about it everyday.
Very interesting read, thanks for sharing your knowledge.

0

10

Roberto Delgado

Nispaara

Justin Tadlock

You should not add roles and capabilities on the admin_init hook. That code will execute on every page load in the WordPress admin, which is something you don’t want to happen. Plus, it stomps on role management plugins when you do that. Adding roles and capabilities in plugins should almost always happen on the plugin activation hook (with a few exceptions, such as the Members plugin, which allows you to manage roles).

You don’t need the current_user_can() check in your show_marketing_info() function since you already added the capability when adding the menu page. WordPress will handle that.

Erica Brooks

I have been using WordPress for years but have not used the different roles available until recently so this post is very helpful. I will check out Role Scoper that you mentioned as I am not so good at the tech stuff and a plug in would be great to manage roles.

0

16

Jeff

You say to never change the default WP roles, which I agree with, but is there any issue in changing the way they’re named? For instance, if “Editor, “Contributor,” etc don’t fit the site’s business and would be better understood by clients to be “Manager,” “Delivery,” etc. WordPress is about so much more than blogging these days.

Daniel Pataki

That’s a tricky question. If you are absolutely sure you know what you’re doing then I think renaming it is fine. You can do so by changing stuff in the $wp_roles global variable.

While I have done this as a test before, I have no idea what WordPress systems rely on naming or some other thing that this would change. I would be surprised if renaming would cause problems, but be extra careful!

Daniel Pataki

That is a great plugin, you are right, it solves a lot of problems for many people. However, these articles aren’t just aimed at people who need to quickly add roles and permissions to their website.

Roles and permissions is something you must be familiar with if your a WordPress developer and utilising them through your own code is a great way to learn. In addition to those who need a specific task completed, there are programmers who need to know the stuff, so they can create awesome plugins like the Members Plugin :)

2

21

steve

This is a great tip.
I’m in the middle of WP user and dev but have always found the plugins for user management OK-ish at best. Knowing this is awesome. And I agree. The reality is, dabbling with code and learning yourself is always miles better than just settling for a plugin!

Subscribe to our email newsletter for useful tips and valuable resources, sent out every second Tuesday.

It's finally here. Smashing Book #5, our new book on real-life responsive design. With front-end techniques and patterns from actual projects, it's a playbook to master all the tricky facets and hurdles of responsive design. Get the book.Free shipping.

Fixing RWD issues can be quite easy — once you understand exactly why they come up. The Mobile Web Handbook will help you understand technical issues on mobile and how to deal with them effectively.

Hungry for more content? Over 60 eBooks are waiting to be discovered in our lovely Smashing Library. And guess what? You can watch Smashing Conference talks there, too.