Roles and Capabilities

Roles and capabilities are two important aspects of WordPress that allow you to control user privileges.

WordPress stores the Roles and their Capabilities in the options table under the user_roles key.

A role defines a set of capabilities for a user. For example, what the user may see and do in his dashboard.

By default, WordPress have six roles:

• Super Admin
• Administrator
• Editor
• Author
• Contributor
• Subscriber

More roles can be added and the default roles can be removed.

Add new roles and assign capabilities to them with add_role() .

function wporg_simple_role() {
	add_role(
		'simple_role',
		'Simple Role',
		array(
			'read'         => true,
			'edit_posts'   => true,
			'upload_files' => true,
		),
	);
}

// Add the simple_role.
add_action( 'init', 'wporg_simple_role' );

Remove roles with remove_role() .

function wporg_simple_role_remove() {
	remove_role( 'simple_role' );
}

// Remove the simple_role.
add_action( 'init', 'wporg_simple_role_remove' );

Capabilities define what a role can and can not do: edit posts, publish posts, etc.

You may define new capabilities for a role.

Use get_role() to get the role object, then use the add_cap() method of that object to add a new capability.

function wporg_simple_role_caps() {
	// Gets the simple_role role object.
	$role = get_role( 'simple_role' );

	// Add a new capability.
	$role->add_cap( 'edit_others_posts', true );
}

// Add simple_role capabilities, priority must be after the initial role definition.
add_action( 'init', 'wporg_simple_role_caps', 11 );

You may remove capabilities from a role.

The implementation is similar to Adding Capabilities with the difference being the use of remove_cap() method for the role object.

Get the role object including all of it’s capabilities with get_role() .

get_role( $role );

Check if a user have a specified role or capability with user_can() .

user_can( $user, $capability );

current_user_can() is a wrapper function for user_can() using the current user object as the $user parameter.

Use this in scenarios where back-end and front-end areas should require a certain level of privileges to access and/or modify.

current_user_can( $capability );

Here’s a practical example of adding an Edit link on the in a template file if the user has the proper capability:

if ( current_user_can( 'edit_posts' ) ) {
	edit_post_link( esc_html__( 'Edit', 'wporg' ), '<p>', '</p>' );
}

The current_user_can_for_blog() function is used to test if the current user has a certain role or capability on a specific blog.

current_user_can_for_blog( $blog_id, $capability );

Codex Reference for User Roles and Capabilities.