Roles and Capabilities

Roles and capabilities are two important features that allow you to extend users with WordPress even more. A role is what your user will be called and the capabilities are what your user can see and do.

What is a Role? What is a Role?

A role is what gives you the power to control what a user will see in their dashboard. In WordPress, there are six default roles: Super Admin, Administrator, Editor, Author, Contributor, and Subscriber. But more roles can be created and can function in many different ways. It can give you more control for what your users see. You can change a user’s role in Dashboard->Users.


Top ↑

Creating New Roles Creating New Roles

In addition to the existing roles, you may create new roles, and assign custom capabilities to them.  Below is some code to create a new role.

function add_simple_role() {
    add_role( 'simple_role', 'Simple Role', array(
            'read' => true,
            'edit_posts' => true,
            'upload_files' => true,
            ) );
//Adds the simple role
add_action('init', 'add_simple_role');

And there you go! You have now created your first role in WordPress. Your role will now how up when you go and change the roles of user.

Top ↑

Manipulating Capabilities Manipulating Capabilities

A capability tells a user role what that role can do (edit posts, publish posts, etc.). Capabilities can also be added for custom post types (edit_your_cpt, read_your_cpt, etc.).

Below is some code to add a capability to the contributor role.

function add_theme_caps() {
    // gets the author role
    $role = get_role( 'contributor' );

    // This only works, because it accesses the class instance.
    // would allow the author to edit others' posts for current theme only
    $role->add_cap( 'edit_others_posts' );
add_action( 'admin_init', 'add_theme_caps');

This gives the contributor role the ability to edit other’s posts with the power of WordPress Capabilities.

It’s also possible to add your own custom capabilities to any role, whether default or custom.  It would have no effect, but then you can test against it in your code.

Top ↑

Using Capabilities Using Capabilities

WordPress has two main functions for checking capabilities, current_user_can and user_can.

current_user_can current_user_can

This function checks capabilities against the currently logged in user.  This would be used by a plugin or theme developer to plan ahead how to allow or restrict access to admin areas, or even front end content.  It does NOT need a user_id, since it’s always working on the current user always.  It accepts a capability and then some args:

<?php current_user_can( $capability, $args ); ?>

The args can provide extra info to the capability. For example you could test for the ability to edit posts, but then also pass in a post_id and test for ability to edit THAT post.

Here’s a practical example of making an Edit link on the front end if the user has the proper capability:

if ( is_user_logged_in() && current_user_can('edit_posts') ) {
  edit_post_link('Edit', '<p>', '</p>');

Top ↑

user_can user_can

This function allows you to check the capabilities of a given user.

<?php user_can( $user, $capability ); ?>

This function is more limited than current_user_can in that it does not accept args for the capabilities. Aside from that they can be used in very similar ways.

Top ↑

Multisite Multisite

The function current_user_can_for_blog() is almost exactly like current_user_can except it takes a blog_id and does NOT accept args. It’s used to test if the current user has a given capability on a specific blog.

<?php current_user_can_for_blog($blog_id, $capability); ?>