current_user_can() │ WP 2.0.0

Whether the current user has a specific capability.

No Hooks.

Return

true|false. Whether the current user has the given capability. If $capability is a meta cap and $object_id is passed, whether the current user has the given meta capability for the given object.

Usage

current_user_can( $capability, ...$args );

$capability(string) (required)

Capability name. See here for the list of roles and capabilities.

$object_id(int) (required)

ID of the specific object to check against if $capability is a "meta" cap.

"Meta" capabilities, e.g. 'edit_post', 'edit_user', etc., are capabilities used by map_meta_cap() to map to other "primitive" capabilities, e.g. 'edit_posts', 'edit_others_posts', etc. Accessed via func_get_args() and passed to WP_User::has_cap(), then map_meta_cap().

Basic List of Capabilities

There are 6 roles in WordPress by default:

Which role the new user gets is specified in Settings > General. The data is saved in an options: users_can_register and default_role:

List of Capabilities by Roles

A list of primitive (fundamental) user caps. These are capabilities that the specified roles (users) have by default. This list of caps is set once, when you install WordPress - it is stored in the database wp_options table in the wp_user_roles option.

• ¹ — when one site (not a multisite).
• ² — when one site (not a multisite). Or enabled in the network settings.
• ³ — this right must be included separately, more below.

Meta Capabilities

Above is a list of primitive (fundamental) rights. But there are also so-called meta-rights. They are not saved anywhere, but are computed "on the fly" and eventually turn into a primitive right.

List of meta-rights:

activate_plugin
activate_plugins
add_comment_meta
add_post_meta
add_term_meta
add_user_meta
add_users
assign_categories
assign_post_tags
assign_term
create_app_password
create_sites
create_users
customize
deactivate_plugin
deactivate_plugins
delete_app_password
delete_app_passwords
delete_categories
delete_comment_meta
delete_page
delete_page
delete_plugins
delete_post
delete_post
delete_post_meta
delete_post_tags
delete_site
delete_sites
delete_term
delete_term_meta
delete_themes
delete_user
delete_user
delete_user_meta
delete_users
edit_app_password
edit_categories
edit_comment
edit_comment
edit_comment_meta
edit_css
edit_files
edit_page
edit_page
edit_plugins
edit_post
edit_post
edit_post_meta
edit_post_tags
edit_term
edit_term_meta
edit_themes
edit_user
edit_user
edit_user_meta
edit_users
erase_others_personal_data
export_others_personal_data
install_languages
install_plugins
install_themes
list_app_passwords
manage_links
manage_network
manage_network_options
manage_network_plugins
manage_network_themes
manage_network_users
manage_post_tags
manage_privacy_options
manage_sites
promote_user
promote_user
publish_post
read_app_password
read_page
read_page
read_post
read_post
remove_user
remove_user
resume_plugin
resume_theme
setup_network
unfiltered_html
unfiltered_upload
update_core
update_https
update_languages
update_php
update_plugins
update_themes
upgrade_network
upload_plugins
upload_themes

edit_term                   — WP 4.7 — It does not check who created the term - it only checks if the specified term and taxonomy exist.
delete_term                 — WP 4.7 —
assign_term                 — WP 4.7 —
activate_plugin             — WP 4.9 — current_user_can( 'activate_plugin', 'my-plugin/my-plugin.php' )
deactivate_plugin           — WP 4.9 — current_user_can( 'deactivate_plugin', 'my-plugin/my-plugin.php' )

export_others_personal_data — WP 4.9.6 — is_multisite() ? 'manage_network' : 'manage_options'
erase_others_personal_data  — WP 4.9.6 — is_multisite() ? 'manage_network' : 'manage_options'
manage_privacy_options      — WP 4.9.6 — is_multisite() ? 'manage_network' : 'manage_options'

update_php                  — WP 5.0 — is_multisite() ? is_super_admin() : update_core
update_https                — WP 5.7 — is_multisite() ? is_super_admin() : manage_options | update_core

create_app_password         — WP 5.7 — map_meta_cap( 'edit_user', $user_id )
list_app_passwords          — WP 5.7 — map_meta_cap( 'edit_user', $user_id )
read_app_password           — WP 5.7 — map_meta_cap( 'edit_user', $user_id )
edit_app_password           — WP 5.7 — map_meta_cap( 'edit_user', $user_id )
delete_app_passwords        — WP 5.7 — map_meta_cap( 'edit_user', $user_id )
delete_app_password         — WP 5.7 — map_meta_cap( 'edit_user', $user_id )

To check such rights, you need to pass additional parameters, such as the ID of the post for which you want to check whether the user can edit it. For example:

if( current_user_can( 'edit_post', 123 ) ){
	 echo 'The current user can edit post 123';
}

In this case, WP checks on the fly whether the user is the author of that post, or has the primitive right to edit all posts. As a result, if the check is passed, this meta right turns into a similar primitive right edit_posts that allows the action to be performed.

Read more about meta rights in map_meta_cap().

Dynamic Capabilities

These are caps that are not stored in the database but are calculated on the fly based on certain conditions. This calculation is done on the hook user_has_cap.

install_languages          — WP 4.9 — update_core  ||  install_plugins  ||  install_themes
resume_plugins             — WP 5.2 — activate_plugins
resume_themes              — WP 5.2 — switch_themes
view_site_health_checks    — WP 5.2 — install_plugins  &&  is_super_admin (multisite)

See wp_maybe_grant_install_languages_cap()
See wp_maybe_grant_resume_extensions_caps()
See wp_maybe_grant_site_health_caps()

unfiltered_upload

By default, the unfiltered_upload capability is available to the administrator. However, this right is locked by default, i.e. roles will not pass the if( current_user_can('unfiltered_upload') ) despite having this right.

To make the unfiltered_upload capability start working as expected, you need to add following constant in wp-config.php:

define( 'ALLOW_UNFILTERED_UPLOADS', true );

With the definition of this constant, roles with unfiltered_upload permission will be able to upload files with any extension (without checking the file type).

For multisite, only the Super Administrator has the unfiltered_upload right. If another role has the unfiltered_upload right, it will simply be ignored. See checking the meta-right in map_meta_cap() for details:

case 'unfiltered_upload':
	if ( defined( 'ALLOW_UNFILTERED_UPLOADS' ) && ALLOW_UNFILTERED_UPLOADS && ( ! is_multisite() || is_super_admin( $user_id ) ) ) {
		$caps[] = $cap;
	} else {
		$caps[] = 'do_not_allow';
	}
	break;

Examples

// is user administrator
if( current_user_can( 'manage_options') ){
	echo 'The user has rights to change settings - it is admin';
}

// define the user globally
global $user;

if( user_can( $user->ID, 'manage_options' ) ){

	// do something that a user with these rights can do
}

if( current_user_can( 'edit_post', 123 ) ) {
	 echo 'The current user can edit post 123.';
}

if( current_user_can( 'edit_term', $term_id ) ){

	echo '<a href=". get_edit_term_link( $term_id ) .'">Edit.</a>";
}

$user = wp_get_current_user();
$allowed_roles = [ 'editor', 'administrator', 'author' ];

if ( array_intersect( $allowed_roles, $user->roles ) ) {

   // Stuff here for allowed roles
}

// if the current user is an editor, the function will return:
current_user_can( 'administrator' ) // false
current_user_can( 'editor' )        // true
current_user_can( 'contributor' )   // false
current_user_can( 'subscriber' )    // false

add_filter( 'user_has_cap', 'user_lower_roles_to_allcaps', 10, 4 );

/**
 * Add lower roles to the list of all caps of current checking user.
 *
 * @param bool[]   $allcaps Array of key/value pairs where keys represent a capability name and
 *                          boolean values represent whether the user has that capability.
 * @param string[] $caps    Required primitive capabilities for the requested capability.
 * @param array    $args    Arguments that accompany the requested capability check.
 * @param WP_User  $user    The user object.
 *
 * @return bool[]
 */
function user_lower_roles_to_allcaps( $allcaps, $caps, $args, $user ){

	$roles_chain = ' > administrator > editor > author > contributor > subscriber > ';

	// do nothing if no need
	if( false === strpos( $roles_chain, $args[0] ) ){
		return $allcaps;
	}

	$low_roles = '';
	foreach( $user->roles as $role ){

		$pos = strpos( $roles_chain, " > $role > " );

		if( false === $pos ){
			continue;
		}

		$_low_roles = substr( $roles_chain, $pos );

		if( strlen( $_low_roles ) > strlen( $low_roles ) ){
			$low_roles = $_low_roles;
		}
	}

	// add top roles to all caps
	$low_roles = explode( ' > ', trim( $low_roles, '> ' ) );
	foreach( $low_roles as $lowrole ){
		$allcaps[ $lowrole ] = 1;
	}

	return $allcaps;
}

$user = get_userdata( 141 );  // editor
var_dump( user_can( $user, 'administrator' ) ); // bool(false)
var_dump( user_can( $user, 'contributor' ) );   // bool(true)
echo "---\n";

$user = get_userdata( 3 );    // author
var_dump( user_can( $user, 'administrator' ) ); // bool(false)
var_dump( user_can( $user, 'contributor' ) );   // bool(true)
echo "---\n";

$user = get_userdata( 1220 ); // contributor
var_dump( user_can( $user, 'administrator' ) ); // bool(false)
var_dump( user_can( $user, 'contributor' ) );   // bool(true)
var_dump( user_can( $user, 'subscriber' ) );    // bool(true)
echo "---\n";

$user = get_userdata( 2486 ); // subscriber
var_dump( user_can( $user, 'administrator' ) ); // bool(false)
var_dump( user_can( $user, 'contributor' ) );   // bool(false)
var_dump( user_can( $user, 'subscriber' ) );    // bool(true)

current_user_can( [ 'administrator', 'author' ] );

/**
 * Checks if the specified role is in the roles of the current/specified user.
 *
 * @param string|array      $roles The name of the role you want to check with the current user.
 * @param empty|int|WP_User $user  Default: current user
 *
 * @return bool
 */
function is_user_role_in( $roles, $user = false ) {

	$user || $user = wp_get_current_user();

	if( is_numeric( $user ) ){
		$user = get_userdata( $user );
	}

	if( empty( $user->ID ) ){
		return false;
	}

	foreach( (array) $roles as $role ){
		if( isset( $user->caps[ $role ] ) || in_array( $role, $user->roles, true ) ){
			return true;
		}
	}

	return false;
}

if( is_user_role_in( [ 'new_role','new_role2' ] ) ){
	echo 'The role of the current user is new_role or new_role2';
}

if( is_user_role_in( [ 'new_role','new_role2' ], 5 ) ){
	echo 'User role 5 new_role or new_role2';
}

Add Your Own Example