Justin Tadlock

Users, roles, and capabilities in WordPress

I recently announced my intention of creating a user/role/capability management plugin for WordPress. One of the things I’ve noticed from the comments on that post is that people don’t understand exactly how the WordPress role and capability system work. Since I’m developing a plugin based on that system, I feel it’s my responsibility to explain how it all fits together.

What I’m proposing in this post is not something new to the WordPress world. I’m not creating new ideas with my upcoming plugin. This is how it works in WordPress. The plugin will just put a face to these ideas.

If you do not grasp this concept, you won’t understand the inherent limitations of the plugin nor the features of it.

What are users?

For the sake of thoroughness (even though you probably understand this), users are people that have registered on your site. They have a user account. Users, in this context, are not people who have visited your site or someone that leaves a comment.

Being a registered user doesn’t mean anything though. Users are given context through a role. Roles define each user’s place on the site.

What are roles?

Roles are a way of grouping users. By default, WordPress gives you several roles to work with:

  • Administrator
  • Editor
  • Author
  • Contributor
  • Subscriber

These are all pretty straightforward. Average Joe shouldn’t have much trouble figuring out what roles can do certain things. But, let me present what’s really going on here.

There are two important things you need to understand about roles in WordPress before moving forward:

  1. Roles are not hierarchical.
  2. Roles have no meaning without capabilities.

Many of you might want to argue with that first point. You might want to say that “administrator” is a higher level than “subscriber.” But, that’s not entirely true. It’s the wrong way to look at how roles work. The default administrator role simply has more capabilities. You could give the default subscriber role more capabilities than the administrator (if you wanted to).

If you learn nothing else from this post, remember this — roles are defined by what capabilities they are granted. There is no hierarchy.

What are capabilities?

This is the real beauty of how the system works. Capabilities are permissions. They’re a way of saying a role can or can’t do something.

Capabilities are given to roles. So, users of a certain role are limited by that role’s capabilities.

For example, the administrator role (by default) is granted the capability of edit_themes. You don’t get to edit your theme because you’re an administrator. You are allowed to edit your theme because your role (administrator) has the capability of edit_themes. If you took away that capability, you would no longer be able to edit your theme in the WordPress admin, no matter how important you think your role is.

Putting it all together

Here’s the short and simple version of this concept:

  • Users are people that have registered on your site.
  • Each user is given a role on your site.
  • Each role is given a set of capabilities (i.e., permissions) that grant/restrict their access.

Why is all this important?

It’s important to understand how the platform you’re using works. I was amazed at the number of comments I recieved that focused on a hierarchical role system, which is not how WordPress works.

That’s the thing that troubles me the most. If people are going to be using a plugin that extends the current role and capability system, they must understand how things work.

A sneak-peek at the plugin

Since many of you have been patiently awaiting news on this plugin and have read through this post, it’s only fair that I offer you a little teaser. This preview is of the Edit Roles component, which is one of several components I’m building into the plugin:

For those of you interested in beta testing the plugin, look for a blog post later this week. The plugin is coming along quite nicely.