When working on a project, the question of adding capabilities to some roles and users sometimes rises. Thanks to high-quality and easiness of WordPress API, we can set our website’s user system as we want. In this article I’ll try to uncover how the users in WordPress act and mention the basics of API, which would be helpful for us when working with roles.

1. What are the roles and capabilities in WordPress?
2. Creating a new user role
3. Editing capabilities
4. Other cases of using roles and capabilities

What are the roles and capabilities in WordPress?

Every user in the system can be given some certain access capabilities to the WordPress functions. This is made by the role system. Every role provides a set of certain capabilities (authorities). There are only 5 roles in WordPress, but it’s usually enough for some easy blog. Let’s look at them a bit closer:

Editor – can edit, publish and delete his own posts, and also upload files/images.
Author – can edit, publish and delete his posts, as well as upload files/images.
Contributor – can edit his posts, but can’t publish them. When contributor creates a post it should be approved by administrator. As soon as the post is approved – it’s published, but contributor still can’t edit it.
Subscriber is your follower. Those are the people, who subscribed for new content. They don’t have any editing privileges. If your blog is open, everyone could subscribe to your updates. Another way of sharing is sending invitations to the people you want to share your blog with.
One more role – Administrator. He’s got the access to everything, including settings, posts, comments and users. *ATTENTION* Be careful when assigning this role to somebody.

Creating a new user role

Let’s now talk about the yummies! We often need to change pre-defined roles or create the new ones when working on a project. For example we need a Userrole, which can upload files but can’t edit or create posts and pages. Not a problem:

add_role( 'file_uploader', 'File Uploader', array( 'upload_files' ) );

In the function we used, the first file_uploader parameter is the name of the role, the second one – display name of role (in our case – the same File Uploader). In the end function gets an array of capabilities inherent to this role (in our case it’s ‘upload_files’). You can always find the full list of capabilities in the codex.

remove_role( 'file_uploader' );

To remove role you can use remove_role().

WordPress Plugin API allows to create new and edit already existing roles! That means we can set the system of our blog users as we want and it’s all is very simple.

But what if we want to change our role, by adding new capabilities?

Editing capabilities

This feature is useful if you want to give someone additional capabilities, without creating new ones. Let’s look at the example of our old upload_files. Let’s assign it to our Authors:

$role = get_role( ‘contributor’ );
$role->add_cap( ‘upload_files’ );

The same method is used for deleting:

$role->remove_cap( ‘upload_files’ );

Other cases of using roles and capabilities

Sometimes it’s important to check if the user has some certain capabilities to perform certain actions. The easiest example that comes to mind: your plugin has some functionality that changes WordPress database and you need to check whether current user is able to perform such actions:

if ( current_user_can( $capability ) ) {
   // do something if the current user has $capability
}

In case you want to check if the user can edit this post, the next function has the unnecessary second argument, pointing at the post ID:

// check whether the current user can edit post with ID $post_id
current_user_can( 'edit_post', $post_id );

In addition, you can change the role and rights exclusively to a single user with WP_User class. This class allows accessing properties, roles and capabilities of a specific user. You can add a meta capability to a certain user regardless of his current role or assign multiple roles to a particular user. At first, we need initialize the user object class before our manipulating:

// get user by user ID
$user = get_user_by('id', $id);

// or get current user
$user = wp_get_current_user();

Congratulations! Now you have an object of your selected user. Now let’s add him another role without modifying  his current role:

$user->add_role( $role_name );

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

$user->remove_role( $role_name );

And of course, the method that replaces the current user’s role:

$user->set_role( $role_name );

We have a set of methods for working with capabilities here:

// check whether the user has a certain capability or role name
if ( $user->has_cap( $cap_name ) ) {
    // do something
}

// add a capability to the user and grant access to that capability
$user->add_cap( $cap_name );

// remove a capability from the user
$user->remove_cap( $cap_name );

// remove all capabilities from the user
$user->remove_all_caps();

Well, I guess that’s it. We looked at the key points of WordPress User Management System. This post is purely theoretical, diving us into the awesome world of WordPress API. If you want some practice and code something useful & cool?? It’s all in the part II of my post. Any feedback would be great, we here at Theme.fm really appreciate it! Goodbye and have a nice theme!