The WordPress permissions system is pretty straight forward, each task a user performs on a WordPress installation requires the capability to perform that task. These capabilities are how a WordPress installation can allow authors to write articles but not edit plugins, or allow editors to manipulate content but not change a theme. The capabilities are very specific, like publish_post or edit_page. The number of capabilities in a WordPress system makes assigning a capability directly to a user fairly unmanageable. To make implementing user permissions a simple and maintainable task, WordPress groups capabilities into roles, like author or administrator. Each role has a set of capabilities that allow a user with that role to accomplish certain tasks and prevent them from performing other tasks. Find more about the roles and capabilities included by default with WordPress.

Default Roles

Wordpress provides the following roles by default:

Super Admin – somebody with access to the site network administration features and all other features. See the Create a Network article.
Administrator – somebody who has access to all the administration features within a single site.
Editor – somebody who can publish and manage posts including the posts of other users.
Author – somebody who can publish and manage their own posts.
Contributor – somebody who can write and manage their own posts but cannot publish them.
Subscriber – somebody who can only manage their profile.

Adding a Role

It is possible to add custom user roles to complement the default roles. An example of this would be adding a guest author role or a registered user role that has access to extra content but cannot edit anything. To add a role we’ll use the WordPress add_role() function. The roles requires us to provide a system name, display name, and define what capabilities the role has.

$role_name    = 'guest_author';
$role_display = __( 'Guest Author' );
$capabilities = array(
	'delete_posts'         => true,
	'edit_posts'           => true,
	'edit_published_posts' => true,
	'upload_files'         => true,
	'read'                 => true,
	'publish_posts'        => false, // Deny capability
	'delete_posts'         => false, // Deny capability
);

$role = add_role( $role_name, $role_display, $capabilities );

if ( $role ) {
	echo 'successfully added a role';
} else {
	echo 'error creating role';
}

Editing a Role

You can edit roles, including the default roles. You can add and remove default capabilities or a custom capability to any role. The steps are simple, get the role, then add or remove a capability. For instance, adding the ability to publish a post to our guest author role and removing the ability to upload files looks like this:

$role       = get_role( 'guest_author' );
$add_cap    = 'publish_posts';
$remove_cap = 'upload_files';

// Add capability
if ( !$role->has_cap( $add_cap ) ) {
	$role->add_cap( $add_cap );
}

// Remove capability
if ( $role->has_cap( $remove_cap ) ) {
	$role->remove_cap( $remove_cap );
}

Checking Capabilities and Permissions

It is also possible to check if a user has a capability using the WordPress user_can() or current_user_can() functions. This allows you to check a user’s permissions before performing custom code or displaying content to a user.

// Show edit link if user can edit posts
if ( current_user_can( 'edit_posts' ); ) {

	echo '<a href="/edit.php">Edit this post</a>';
}