current_user_can()
Whether the current user has a specific capability.
This function should be used after the plugins_loaded action. By default WordPress setups current user on the init hook.
Note: Will always return true if the current user is a super admin, unless specifically denied.
Explicitly denying the capability by using $user->add_cap( 'capability', false )
will not work. The only way to explicitly deny a capability for super admins is to use the map_meta_cap filter to return do_not_allow
for checks for that capability.
Use user_can() to check the capabilities of the specified user.
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
Build In PostThere are 6 roles in WordPress by default:
Super Admin | Super Administrator. Has rights to manage the network sites. This role appears only in multisite installation. |
administrator | The administrator of the site (a separate site in the network multisite). |
editor | Editor. Has access to all posts, pages, comments, categories, tags, and links. |
author | Author. Can create, upload photos, edit and publish his posts. |
contributor | Contributor. Can create posts, which are then published by an editor or administrator. |
subscriber | Subscriber. Can't do anything except edit profile. |
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.
Capability | Super-admin | Admin | Editor | Author | Contributor | Subscriber |
---|---|---|---|---|---|---|
read | yes | yes | yes | yes | yes | yes |
delete_posts | yes | yes | yes | yes | yes | |
edit_posts | yes | yes | yes | yes | yes | |
delete_published_posts | yes | yes | yes | yes | ||
edit_published_posts | yes | yes | yes | yes | ||
publish_posts | yes | yes | yes | yes | ||
upload_files | yes | yes | yes | yes | ||
delete_others_pages | yes | yes | yes | |||
delete_others_posts | yes | yes | yes | |||
delete_pages | yes | yes | yes | |||
delete_private_pages | yes | yes | yes | |||
delete_private_posts | yes | yes | yes | |||
delete_published_pages | yes | yes | yes | |||
edit_others_pages | yes | yes | yes | |||
edit_others_posts | yes | yes | yes | |||
edit_pages | yes | yes | yes | |||
edit_private_pages | yes | yes | yes | |||
edit_private_posts | yes | yes | yes | |||
edit_published_pages | yes | yes | yes | |||
manage_categories | yes | yes | yes | |||
manage_links | yes | yes | yes | |||
moderate_comments | yes | yes | yes | |||
publish_pages | yes | yes | yes | |||
read_private_pages | yes | yes | yes | |||
read_private_posts | yes | yes | yes | |||
unfiltered_html | yes | yes ¹ | yes ¹ | |||
activate_plugins | yes | yes ² | ||||
create_users | yes | yes ¹ | ||||
deactivate_plugins | yes | yes | ||||
delete_plugins | yes | yes ¹ | ||||
delete_themes | yes | yes ¹ | ||||
delete_users | yes | yes ¹ | ||||
edit_dashboard | yes | yes | ||||
edit_files | yes | yes ¹ | ||||
edit_plugins | yes | yes ¹ | ||||
edit_theme_options | yes | yes | ||||
edit_themes | yes | yes ¹ | ||||
edit_users | yes | yes ¹ | ||||
export | yes | yes | ||||
import | yes | yes | ||||
install_languages | yes | yes ¹ | ||||
install_plugins | yes | yes ¹ | ||||
install_themes | yes | yes ¹ | ||||
list_users | yes | yes | ||||
manage_options | yes | yes | ||||
promote_users | yes | yes | ||||
remove_users | yes | yes | ||||
switch_themes | yes | yes | ||||
update_core | yes | yes ¹ | ||||
update_languages | yes | yes ¹ | ||||
update_plugins | yes | yes ¹ | ||||
update_themes | yes | yes ¹ | ||||
unfiltered_upload | yes ³ | yes ³ | ||||
manage_network_options | yes | |||||
manage_network_plugins | yes | |||||
manage_network_themes | yes | |||||
manage_network_users | yes | |||||
manage_network | yes | |||||
manage_sites | yes | |||||
setup_network | yes | |||||
upgrade_network | yes |
¹
— 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().
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
#1 Whether a user is an administrator
if( current_user_can('manage_options') ){ echo "The user can manage options!"; }
#2 Use user_can() to check the capabilities of the current user
global $user; if( user_can($user->ID, 'manage_options') ){ // do something };
manage_options - administrator's capibility
#3 Using $object_id
if( current_user_can('edit_post', 123) ) { echo 'Current user can edit post 123'. }
#4 Check the capability for specific taxonomy item
Since 4.7 you can check the capabilities for specific terms using edit_term, delete_term, assign_term.
This example displays a link for editing term item only if the user has specific capability:
if( current_user_can('edit_term', $term_id) ){ echo '<a href="'. get_edit_term_link( $term_id ) .'">Edit.</a>'; }
#5. Check more than two roles
If you want to check more than two roles, you can check if the roles of the current user is inside an array of roles, something like:
$user = wp_get_current_user(); $allowed_roles = array( 'editor', 'administrator', 'author' ); if ( array_intersect( $allowed_roles, $user->roles ) ) { // Stuff here for allowed roles }
Verify the role of the current user
Don't pass the name of the role to this function because the verification may work incorrectly. An example of how not to do it:
// if the current user is editor, the function returns: current_user_can('administrator') // false current_user_can('editor') // true current_user_can('contributor') // false current_user_can('subscriber') // false
Instead, you can use:
#1 First function
/** * Checks the role of a specific user. * * @param string $role Name of the role. * @param bool $user_id (optional) User ID to check the role against. * * @return bool */ function is_user_role( $role, $user_id = null ) { $user = is_numeric( $user_id ) ? get_userdata( $user_id ) : wp_get_current_user(); if( ! $user ){ return false; } return in_array( $role, (array) $user->roles, true ); } // Using for the current user if( is_user_role( 'customer' ) ){ echo "Yeap"; } else{ echo "Nope"; } // Using for the specific user. $user_id = 23; if( is_user_role( 'customer', $user_id ) ){ echo "Yeap"; } else{ echo "Nope"; }
#2 Second function
I wrote this function in the process of working on one of the projects, now I use it periodically:
/** * Checks if the specified role is in the roles of the current (or specified) user. * * @param array|string $roles Name of the role to check the user against. * @param int|WP_User $user * * @return bool */ function is_user_role_in( $roles, $user = null ) { if( ! $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; } // Examples of usage if( is_user_role_in( [ 'new_role', 'new_role2' ] ) ){ echo 'The current user has role "new_role" or "new_role2"'; } if( is_user_role_in( [ 'new_role', 'new_role2' ], 5 ) ){ echo 'User 5 has role "new_role" or "new_role2"'; }
Notes
- See: WP_User::has_cap()
- See: map_meta_cap()
Changelog
Since 2.0.0 | Introduced. |
Since 5.3.0 | Formalized the existing and already documented ...$args parameter by adding it to the function signature. |
Since 5.8.0 | Converted to wrapper for the user_can() function. |
Code of current_user_can() current user can WP 5.9.3
function current_user_can( $capability, ...$args ) { return user_can( wp_get_current_user(), $capability, ...$args ); }