How to Add New User Roles in WordPress

Posted on

WordPress allows different users have have varying sets of permissions. This enables Administrators to delineate specific functionality to contributors without worrying about them having access to sensitive portions of the site. For example, you might want someone to be able to add new articles to the site without giving them access to the plugins or the themes. WordPress achieves this via the “Roles” feature. Each role consists of a certain set of permissions that you can then apply to any given member. Typical roles included by default are admin, editor, author, contributor, and subscriber.

existing roles

These work pretty well for most installations. But what if you have a unique set of permissions that don’t fit into any pre existing category? Luckily, WordPress allows you to add new user roles using PHP, thereby giving you the freedom to arrange and delegate according to your preferences.

For this example, I’m going to create a new user role that allows those to whom it is assigned the ability to add new posts, edit them, moderate comments, as well as the ability to install new plugins, activate, and delete them.

Using the “add_role” PHP Function

WordPress doesn’t provide any inbuilt graphical interface for creating new roles, probably due to the fact that it’s a relatively niche functionality and that most people will make do with the ones already built in. But for those requiring a bit more, there is a convenient PHP function that allows us to specify exactly what permissions to assign. That function is called “add_role”. It takes three parameters:

  • The Internal Role Name;
  • The Display Name;
  • An array of permissions.

For my test example, I’m going to use the following three values corresponding to the above three variables, namely:

  • my_custom_role
  • My Custom Role
  • An array of read/write and plugin management key/value pairs

If the function succeeds, it returns a WP_Role object and returns null if the role already exists. We can use this check to display a “Success” or “Error” message as necessary.

When and Where do We Run the Code?

We want the new role to be created only once. While WordPress won’t create a duplicate role if the same one already exists, we typically want the code itself to execute only a single time. An ideal place for this to happen is when your plugin is just being activated, since the most common use case scenario is the creation of a new role by a plugin author.

But in our case we don’t want to create a new plugin. So we simply add the code to our functions.php file, check to see whether it has run successfully, and then delete it. To do this, I hook into the “init” action hook and run the code there. Here is the code I use at the bottom of functions.php:

function add_roles_on_init() {
      $role_created= add_role(
      'my_custom_role', __( 'My Custom Role' ),
       'read' => true,
       'edit_posts' => true,
       'delete_posts' => false,
       'activate_plugins' => true,
       'delete_plugins' => true,
       'edit_plugins' => true,
       'install_plugins' => true,
       'update_plugins' => true,
 if ( null !== $role_created ) {
       echo 'Contribute and Manage Plugins Role Created!';
else {
      echo 'You already have this role!';
add_action('init', 'add_roles_on_init');

Note how I assign “true” to the various features that I want to give my new role. You can get a comprehensive list of such features from the WordPress Codex.

After pasting this code at the end of my functions.php, and saving the file in the inbuilt WordPress editor, I get the following message when the page reloads:

created message

It’s a bit clumsy to be sure, running it like this. But it suits our purpose. As soon as I know that the role has been created, I go back and delete the code I just put in, restoring functions.php to what it was before. Now let’s go and see if our new role actually does show up. Under “Users” on the left hand side of the WordPress dashboard, click “Add New”. Scroll down to the last form element called “Role” and click the drop down box.

role created

As you can see, our new role called “My Custom Role” has been added and can be assigned to any new person I choose. You can use this quick technique to craft a finely honed WordPress management strategy without any plugins.

Leave a Reply

Your email address will not be published. Required fields are marked *