An Introduction to WordPress Roles & Capabilities

WordPress comes with a set of access controls that allow you to give certain roles capabilities. Those roles, in turn, get assigned to users. This is why contributors can write and edit their own posts, but administrators can edit and work with everyone’s posts in the WordPress admin. Contributor and Administrator are both roles with differing sets of capabilities.

In this post, I’ll explain how you can add your own roles and add additional capabilities to role.

The first rule of adding roles and capabilities is that you only need to do it once. The best place to do that, of course, is a plugin activation hook. Roles are stored in the database, so you need not add them on every page load in the same way that post types are added.

The concept is simple: call register_activation_hook to set up a function that gets called during plugin activation and call add_role in the hooked function. add_role tags three arguments: the role key/id, the role’s label, and an array of capabilities.

Let’s add a new role that only has the read capability, giving the role’s users access to the admin area and their profile but nothing else.

<?php

register_activation_hook(__FILE__, ‘pmg_roles_activate’);

/**

* Activation hook. Adds roles and capabilities.

*

* @since   1.0

* @uses    add_role

* @return  null

*/

function pmg_roles_activate()

{

add_role(‘former_employee’, __(‘Former Employee’, ‘pmg’), array(

‘read’ => true

));

}

And of course, we need a deactivation function to remove that role as well with delete_role.

<?php

register_deactivation_hook(__FILE__, ‘pmg_roles_deactivate’);

/**

* Remove our additional roles and caps.

*

* @since   1.0

* @uses    remove_role

* @return  null

*/

function pmg_roles_deactivate()

{

remove_role(‘former_employee’);

}

While you can add capabilities when adding a role, you can also add capabilities to an already existing role. Capabilities, like roles themselves, are stored in the database – you only need to add caps on plugin activation and remove them on deactivation.

The process is simple: call get_role to retrieve and WP_Role object. You can then call that object’s add_cap method to grant the permission you want.

Let’s allow our authors and contributors to post unfiltered HTML (maybe a bad idea? but we trust ’em, right?!).

<?php

register_activation_hook(__FILE__, ‘pmg_roles_activate2’);

/**

* Activation hook. All contributors and authors to post unfiltered HTML

*

* @since   1.0

* @uses    add_role

* @return  null

*/

function pmg_roles_activate2()

{

foreach(array(‘contributor’, ‘author’) as $r)

{

$role = get_role($r);

if($role)

{

$role->add_cap(‘unfiltered_html’);

}

}

}

The corresponding deactivation hook called the remove_cap method.

<?php

register_deactivation_hook(__FILE__, ‘pmg_roles_deactivate2’);

/**

* Remove our additional roles and caps.

*

* @since   1.0

* @uses    remove_role

* @return  null

*/

function pmg_roles_deactivate2()

{

foreach(array(‘contributor’, ‘author’) as $r)

{

$role = get_role($r);

if($role)

{

$role->remove_cap(‘unfiltered_html’);

}

}

}

WordPress’ user management system and roles and capabilities have a lot more to offer than this, of course. One could build entire membership sites and much more.