Handling WordPress User Roles

Wordpress comes with an inbuilt user manager to allow you to have full flexibility on the users of your Wordpress site. The security system it uses has users, roles and capabilities. A user can have multiple roles, these roles can have different capabilities, capabilities define if you have access to perform a certain task or not. For example user A can have a role of editor, this role has capabilities to edit, publish and delete their own posts. The different capabilities allows the blog owner to use different functions in the Wordpress site such as write posts, moderate comments, create new pages, creating new categories and tags, manage plugins, manage themes and managing other site users.

#Roles And Capabilities Of Wordpress Users

There are different types of users that can use your Wordpress site, these different types of users can have different roles. The user can be one of five different roles: - Subscriber

• Contributor
• Author
• Editor
• Administrator
• Super Administrator

Each of these roles have different security access in Wordpress, some can just read posts, some can write posts but not publish them and others have full access to the Wordpress site.

#Subscriber

This is the lowest level of Wordpress users and can only view their own profile and only read posts on the Wordpress site.

#Capabilities

• read

#Contributor

A contributor is a user that can write their own posts but they are not able to publish them on the site. This is the ideal role to have for guest posters, it allows them full control to write the post but can't be published without the editor approval.

#Capabilities

• delete_posts
• edit_posts
• read

#Author

The author is the next level up from the * contributor*, they are able to have full control over their own posts but they have access to publish the post to the site.

#Capabilities

• delete_posts
• delete_published_posts
• edit_posts
• edit_published_posts
• publish_posts
• read
• upload_files

#Editor

The editor role is someone who can write their own posts and manage each of their own posts but they can also manage all the other posts on the site by any author.

#Capabilities

• delete_others_pages
• delete_others_posts
• delete_pages
• delete_posts
• delete_private_pages
• delete_private_posts
• delete_published_pages
• delete_published_posts
• edit_others_pages
• edit_others_posts
• edit_pages
• edit_posts
• edit_private_pages
• edit_private_posts
• edit_published_pages
• edit_published_posts
• manage_categories
• manage_links
• moderate_comments
• publish_pages
• publish_posts
• read
• read_private_pages
• read_private_posts
• unfiltered_html
• upload_files

#Administrator

This is the main role for the site and can have full control over the site, change theme, plugins, write posts, read posts, delete posts they can do what ever they want.

#Capabilities

• activate_plugins
• create_users
• delete_others_pages
• delete_others_posts
• delete_pages
• delete_plugins
• delete_posts
• delete_private_pages
• delete_private_posts
• delete_published_pages
• delete_published_posts
• delete_users
• edit_dashboard
• edit_files
• edit_others_pages
• edit_others_posts
• edit_pages
• edit_posts
• edit_private_pages
• edit_private_posts
• edit_published_pages
• edit_published_posts
• edit_theme_options
• export
• import
• list_users
• manage_categories
• manage_links
• manage_options
• moderate_comments
• promote_users
• publish_pages
• publish_posts
• read_private_pages
• read_private_posts
• read
• remove_users
• switch_themes
• unfiltered_upload
• upload_files

#Super Admin User

The super admin user is for multi-site Wordpress installs, this user has all the capabilities as the admin user but can also create new sites, network themes, network plugins and network users. - manage_network

• manage_sites
• manage_network_users
• manage_network_themes
• manage_network_options

#Create A New Role

The above roles are the default roles you find in Wordpress, but if you need additional roles in your Wordpress site you can create new roles. To create a new role all you have to do is use the function add_role().

<?php add_role( $role, $display_name, $capabilities ); ?> 

This function takes three parameters:

• $role - Name of the new role
• $display_name - Display name of the new role
• $capabilities - This is an array define where the role has access to and where they are denied from.

$result = add_role('new_role_created', 'New Role', array(
    'read' => true,
    'edit_posts' => true,
    'delete_posts' => false, 
));

Defining each of the role values as true means this role is granted access to this capability, setting the value to false will deny access to this capability.

#Remove An Existing Role

As you can add new roles you also have the ability to remove existing roles in the code. This is useful if you don't want any users to have a certain role on your website. To delete a role you use the function remove_role().

<?php remove_role( $role ); ?> 

This function takes one parameter which is the name of the role.

<?php remove_role( 'subscriber' ); ?>

#Get A Role

If you want to find out what a role does you can use the Wordpress function get_role(), this function will return a WP_Role object populated with the data about the role include capabilities and the name of the role.

<?php $wp_role_obj = get_role( $role ); ?> 

This takes one parameter which is the role name. On this object you can use three methods - add_cap($cap, $access) - Adds a capability to the role,

• has_cap($cap) - Checks to see if the role has this capability will return true or false.
• remove_cap($cap) - Removes a capability from the role.

Here is a code snippet to allow authors to edit other peoples posts.

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

    // 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');

Source: add_cap. Here is an example of using the remove_cap method.

add_action( 'admin_init', 'remove_editor_read_private_posts' );

function remove_editor_read_private_posts(){
  $role = get_role( 'editor' );
  $role->remove_cap( 'read_private_posts' );

  // or you can simply use: 

  remove_cap( 'editor', 'read_private_posts' );
}

#Check A Users Capabilities

Sometimes in your code you need to check the current capabilities of the user so you can allow the user to do different things. In Wordpress you have the function current_user_can( $cap ) which returns a boolean on if the user has these capabilities.

if ( current_user_can('moderate_comments') ) {
    echo 'The current user can moderate comments';
}

If you are outside of The Loop you can pass through a second parameter of a post Id to check capabilities on a certain post.

if ( current_user_can('edit_post', 123) ) {
    echo 'The current user can edit post 123'.
}

#Using The WP_User Class

In version 3.3 Wordpress introduced the WP_User which makes it really easy to make changes to the current user. To create a new instance of this object you use the function wp_get_current_user().

$user = wp_get_current_user();

This has created a new instance of the WP_User class populated with the data of the current user, you now have access to methods to change your user. ### Check If User Exists

There is a method on the user object which you can use to check the current user exists.

$user = wp_get_current_user();

if($user->exists()) { // User exists } else { // User does not exist } ### Get User Meta Values

There is a method get() which will allow you to get meta data attached to the user.

$user = wp_get_current_user();

$meta = $user->get( $meta_key );

#Get All The Capabilities Of The User

Set the role property on the User class.

$user = wp_get_current_user();

$user->get_role_caps( );

#Add A Role

Add a new role to the user.

$user = wp_get_current_user();

$user->add_role( $role_name );

#Remove A Role

Remove a role from a user.

$user = wp_get_current_user();

$user->remove_role( $role_name );

#Modify The User Role

Change the user role to something else, this will remove the current role and set the new role.

$user = wp_get_current_user();

$user->set_role( $role_name );

#Add Additional Capabilities

Add new capabilities to your Wordpress user.

$user = wp_get_current_user();

$user->add_cap( 'create_users' );

#Remove Capabilities

Remove a user capabilities of performing a function.

$user = wp_get_current_user();

$user->remove_cap( 'create_users' );

#Remove All Capabilities

Remove all the capabilities this user has.

$user = wp_get_current_user();

$user->remove_all_caps( );

#Check User Capabilities

Check if this user has the capabilities you are looking for.

$user = wp_get_current_user();

 if($user->has_cap( 'create_users' )) { 
    // User can create users 
} else { 
    // User does not have access to create users 
} 

That's it...this is how you can customise your Wordpress users. Please let me know what ways you have used the above functions to customise your Wordpress users.