New current_user_has_role function to work for roles like current_user_can does for caps

[sc0ttkclark]

current_user_can( 'capability' ) is great, but it would save some code and be more reliable if we had something like this for roles as a global function that's easy to get at:

current_user_role( 'editor' ) would return true if the user has the editor role, false if they weren't.

I'll work on a patch for this when I get a moment, this is just here to remind me and let others know what I'm thinking.

current_user_can( 'editor' ) also works.

According to PHPDocs, the parameter is either a capability or a role name:
http://core.trac.wordpress.org/browser/tags/3.4.2/wp-includes/capabilities.php#L1194

However, there's some inconsistency (also mentioned in #20824).

On single site, current_user_can( 'editor' ) returns false for administrator, only current_user_can( 'administrator' ) returns true.

On Multisite, current_user_can( 'editor' ) returns true for super admin.

Right, in the case of Multisite, this function would return true only if the user was that specific role.

But via the WP codex itself: ​http://codex.wordpress.org/Function_Reference/current_user_can

Do not pass a role name to current_user_can(), as this is not guaranteed to work correctly.

This would also mean if a capability is added that matches the role, there won't be confusion within the code as this function would only look at the actual roles.

And maybe this function should be named current_user_has_role to make more sense.

Replying to sc0ttkclark:

Right, in the case of Multisite, this function would return true only if the user was that specific role.

From my testing, it's vice versa, that's only the case on single site.

Do not pass a role name to current_user_can(), as this is not guaranteed to work correctly.

Looking at the page history, seems that the sentence was also added because of #20824.