in WordPress

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](http://codex.wordpress.org/Function_Reference/add_cap). Here is an example of using the [remove\_cap](http://codex.wordpress.org/Function_Reference/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 )](http://codex.wordpress.org/Function_Reference/current_user_can) 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()](http://codex.wordpress.org/Function_Reference/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.

Upgrade to access all content on Paulund

Members unlock all tutorials and snippets

Access to all downloadable content

Access to code examples before others

Sign Up Now

Already a member? Login here

Subscribe To The Weekly Newsletter

Get weekly updates to your email