CentrioHost Blog

Anytime a site viewer signs-up for an account, or you manually add a new user in Admin Users Screen, WordPress registers essential user data in wp_users and wp_usermeta tables. The new user gets the username of his choice, a password, an email address, a role which determines what she can view in the admin panel. But what exactly are WordPress user roles?

WordPress User Roles and Capabilities

The WordPress user management system is based on two key concepts: Roles and Capabilities.

• A Role identifies a group of users who are allowed to execute the same tasks onto the website.
• A Capability is the ability (or permission) to perform each single task assigned to a role.

Out of the box, WordPress comes with six roles:

• Super Administrator is a user who has full access to multisite features: she can create and manage sub-sites, create and manage network users, install and remove themes and plugins and enable them on the network.
• Administrator is a user who has full access to the administration features of a regular WordPress installation.
• Editor is a user who can edit and publish content created by any user.
• Author can publish and edit his own content.
• Contributor can create and edit but not publish his own content.
• Subscriber can only access his profile.

These WordPress user roles are hierarchically ordered, meaning that higher-level roles have the same capabilities of lower roles, plus a number of role-specific capabilities.
Consider the following table:

A Contributor has the same read capability as a Subscriber, but she has two more capabilities, edit_posts and delete_posts, which are specific for this role: the contributor can create, edit and delete his own not published posts.
An Editor has the same capabilities as a Contributor, and in addition she can publish, edit and delete her own posts, and upload media files.

We have to make a distinction between two types of capabilities:

• Meta Capabilities depend on the context (i.e. the logged-in user and the current post/page).
• Primitive Capabilities do not depend on the context (i.e. edit posts created by other users)

A user can edit a post if she’s the post author (‘edit_post’ meta capability) or if she has the capability to edit posts created by other users (‘edit_others_posts’ primitive capability).
WordPress automatically translates meta capabilities into one or more primitive capabilities for regular posts, but when using post types we have to manually map meta caps to primitive capabilities.
See the Codex for a comprehensive list of the built-in capabilities.

Default roles and capabilities usually suffice to the most common requirements of a website, but sometimes you’ll be asked to provide the site admin with a more granular control over what users can see and do.
Luckily, as WordPress users and/or developers, we are not limited to default roles and capabilities, because WordPress allows us to create new capabilities and new roles, and assign different sets of capabilities to existing roles. As an example, you can assign to Subscribers the capability to create and edit posts, and/or assign to Contributors the capability to publish. But you can get much more from the user management system:

• you can show/hide front-end elements – like menu items, posts or widgets – depending on the user role
• you can customize the post content by user
• you can restrict access to specific site sections for specific users or roles
• you can create custom post types with customized capabilities which can be differently declined for each role

This latter point marks the goal of this post.

Students, Teachers, and Homework

Say you’re building an educational website where students and teachers are allowed to interact with each other. Students should create projects and submit them for review.
Teachers should be able to edit student projects and publish them if approved.
Comments are allowed: students can comment any project, but only teachers can moderate comments.
Here is our to-do list:

• Add student and teacher user roles
• Register the student_project post type and the subject custom taxonomy
• Register and map specific capabilities for the student_project post type
• Assign capabilities to administrator, student and teacher roles

We will dissect the topic mostly from a developer’s perspective, building a plugin that registers custom post type and taxonomy, roles and capabilities. But we won’t forget non-developers, and in the final part of this post I will suggest some of the most popular and comprehensive plugins you’ll find to manage user roles and caps like a pro without writing one single line of code.

Before reading through the article, have a look at the plugin code on Gist

Register WordPress User Roles and Capabilities

Students will be allowed to read all projects, and create, edit and delete their own projects. They won’t be allowed to publish any project, nor edit and delete published projects.
Teachers should control every aspect of project administration. They will be allowed to create new projects, and edit, delete and publish projects created by any user.

That being said, let’s register student and teacher roles:

function centriohost_add_roles() {
	add_role( 'student', 'Student', array( 
		'read' => true, 
		'edit_posts'   => true, 
		'delete_posts' => true ) );
	add_role( 'teacher', 'Teacher', array( 
		'read' => true, 
		'edit_posts'   => true, 
		'delete_posts' => true,
		'delete_published_posts' => true,
		'publish_posts' => true,
		'upload_files' => true,
		'edit_published_posts' => true,
		'manage_categories' => true ) );
}
register_activation_hook( __FILE__, 'centriohost_add_roles' );

• register_activation_hook registers a function to be run when a plugin is activated. Here it is preferable to an action hook like init, because the new roles are registered into the database, and we don’t need to run the function anytime WordPress loads. register_activation_hook keeps two arguments: the path to the main file of the plugin (__FILE__), and the callback function to be run (‘centriohost_add_roles’).
• On plugin activation, register_activation_hook is executed, and add_roleregisters the new role in wp_options table if it does not exist. This second function keeps three arguments: role name, display name and an array of capabilities.

The callback function adds two roles. Each role is provided with a different set of capabilities: students will be allowed to read public posts, create, edit and delete their own posts if not published. Tea