Customize user roles
Sometimes the default roles and capabilities aren’t exactly what you need for your site. If you need to create new roles or modify existing ones, we have helper functions to assist you. Please use these functions rather than the traditional methods as this will ensure that your code works on WordPress VIP and in your development environments.
As an example, here’s how you can register a “Reviewer” role:
add_action( 'admin_init', function() {
$ver = 42; // bump each time this code is changed
// check if this has been run already
if ( $ver <= get_option( 'myplugin_roles_version' ) ) {
return;
}
// add a Reviewer role
wpcom_vip_add_role( 'reviewer', 'Reviewer', array(
'read' => true,
'edit_posts' => true,
'edit_others_posts' => true,
'edit_private_posts' => true,
'edit_published_posts' => true,
'read_private_posts' => true,
'edit_pages' => true,
'edit_others_pages' => true,
'edit_private_pages' => true,
'edit_published_pages' => true,
'read_private_pages' => true,
)
);
// update the version to prevent this running again
update_option( 'myplugin_roles_version', $ver );
} );Note
You’ll want to use these helper functions on the ‘admin_init‘ hook, and ensure you only run them when the role definitions need to change, because they trigger a database update. An example technique is shown that triggers only when a version changes.
If you have different plugins that customize roles, each should have a separate option.
Caution
If your site has a high amount of traffic, or a lot of editors active at once, then we’d highly recommend putting the update behind an admin button, on a special settings page, or create a CLI command to trigger the roles update. That will avoid a sudden spike of multiple identical DB updates that can be triggered when a change like this is made during a high traffic period. Such spikes can cause performance issues.
You can find a list of all capabilities available in WordPress core in the WordPress Handbook.
Here are some more examples:
add_action( 'admin_init', function() {
$ver = 43; // bump each time this code is changed
// check if this has been run already
if ( $ver <= get_option( 'myplugin_roles_version' ) ) {
return;
}
// Add new role
wpcom_vip_add_role( 'super-editor', 'Super Editor', array( 'level_0' => true ) );
// Remove publish_posts cap from authors
wpcom_vip_merge_role_caps( 'author', array( 'publish_posts' => false ) );
// Remove all caps from contributors
wpcom_vip_override_role_caps( 'contributor', array( 'level_0' => false ) );
// Duplicate an existing role and modify some caps
wpcom_vip_duplicate_role( 'administrator', 'station-administrator', 'Station Administrator',
array( 'manage_categories' => false ) );
// Add custom cap to a role
wpcom_vip_add_role_caps( 'administrator', array( 'my-custom-cap' ) );
// Remove cap from a role
wpcom_vip_remove_role_caps( 'author', array( 'publish_posts' ) );
// update the version to prevent this running again
update_option( 'myplugin_roles_version', $ver );
} );