WordPress Create Custom Roles and Capabilities

Techniques » WordPress Create Custom Roles and Capabilities

Filed under: PHP, Techniques, Wordpress by Corey - June 11, 2010

So you want to add a custom Role to your WordPress site to add more flexibility when assigning users their role, what do you do? Simply add a role, with a few lines of code in your theme’s functions.php file, using WordPress’ add_role() function, as defined below.

1	add_role( $role_name, $display_name, $capabilities );

The example below adds a role of Video Manager with a custom cabability of ‘manage videos’.

1	add_role( 'video_manager, 'Video Manager', array( 'manage_videos' ) );

NOTE: Once you add this code to your functions.php file and view any page on your site to make the role addition, you can and should comment it out so that it doesn’t run on every page view.

Now, how do we use this new role with the new capability you ask? Simply use the WordPress current_user_can() function to check the user’s capability.

1
2
3

if ( current_user_can( 'manage_videos' ) ) {
    // let them manage those videos!
}

This technique can be combined with our WordPress Role Capability Restriction technique to add even more capabilities to your new custom role. Simply create your new role then use it in the get_role() function call detailed in our technique.

About Corey

Corey was born, raised, and still lives in CMCH, NJ (about 5 minutes outside of Wildwood). He loves the Jersey Shore, and has loads of sand in his shoes! He has been involved with computers and programming since first purchasing a Commodore 64 in 1984. Corey formally began a web design company in 2004, ever broadening his progamming languages and skills since. code

View all posts by Corey →

12 Responses to WordPress Create Custom Roles and Capabilities

Peter Goes says:

January 28, 2011 at 5:26 am

What do you mean with the note that the code should be comment out while make role additions?

tnx, Peter

Reply
- Corey says:
  
  January 28, 2011 at 6:03 am
  
  Good question, I should have been clearer with those instructions. The “add_role( ‘video_manager, ‘Video Manager’, array( ‘manage_videos’ ) );” adds a role to WordPress by adding an entry to the database, and only needs to be run once, adding a double slash // before the code will comment it out. So once you add this code to your functions.php file, view any page on your site, then you should comment it out. Otherwise the add_role will be run on every page view unnecessary, even though the role will only be added once to the database. The resulting code will look like this: // add_role( ‘video_manager, ‘Video Manager’, array( ‘manage_videos’ ) );. I hope this clarifies my post.
  
  Reply
  - Peter Goes says:
    
    February 10, 2011 at 8:39 am
    
    Thank you for the reply. I see why you don’t want to run the code every page refresh.
    But isn’t there some kind of hook/action the where add_role should be put in?
    It seems like a bit of a hack this way.
Peter Goes says:

February 10, 2011 at 8:43 am

I looked it up in the doc’s, when add_role is called, it check’s if the role exists, if not, it put’s it in the database.
http://core.trac.wordpress.org/browser/tags/3.0.5/wp-includes/capabilities.php
line: 136
So I think you can leave it uncommented.

Reply
- Corey says:
  
  February 11, 2011 at 8:43 am
  
  Thanks for the reference material, we really appreciate your investigation. I just prefer to comment it out so there is less for the server to do unnecessarily.
  
  Reply
Geert says:

March 19, 2011 at 1:49 am

Hi,

Checking against a custom capability, like :
if ( current_user_can( ‘manage_videos’ ) )
does not work here in WP 3.0.1

add_role seems to write the name of the ROLE to the wp_capabilities fields in wp_usermeta, not the name of the custom CAPABILITY.

Came across this?

Thx.

Reply
- Corey says:
  
  March 19, 2011 at 2:18 am
  
  You are correct, there seems to be an issue with WP 3.0+ and the current_user_can() function, see this WP Forum post: http://wordpress.org/support/topic/current_user_can-not-working-with-custom-roles?replies=5
  
  Reply
  - Corey says:
    
    March 19, 2011 at 2:21 am
    
    Well Geert, it seems you were 23 minutes ahead of me! I neglected to read who had made posts on this Forum topic, the latest post is you! We will investigate and post any findings here. Thanks!
  - Corey says:
    
    May 30, 2011 at 12:18 am
    
    It seems the issue with WP 3.0+ and the current_user_can() function has been resolved with the 3.1.1+ versions of WordPress. See havahula’s post regarding his successful “double-bump” technique: http://wordpress.org/support/topic/current_user_can-not-working-with-custom-roles?replies=5#post-2092066
anup says:

June 1, 2011 at 8:32 am

thanks

Reply
Trent says:

October 19, 2011 at 2:37 am

This is a fairly old post – but for those of you concerned with server overhead, you may wish to create a little plugin that does this on “activation” – then just deactivate it.

I do this occasionally when I have one off things to do.

Reply
- Corey says:
  
  October 19, 2011 at 5:13 am
  
  Thanks Trent, this is a great idea, and we welcome input no matter the age of our posts.
  
  Reply