map_meta_cap( string $cap, int $user_id, mixed $args ): string[]
- Since
- 2.0.0, 4.9.6, 5.1.0, 5.2.0, 5.3.0, 5.7.0, 6.7.0
- Source
wp-includes/capabilities.php:45
Maps a capability to the primitive capabilities required of the given user to satisfy the capability being checked.
Description
This function also accepts an ID of an object to map against if the capability is a meta capability. Meta capabilities such as
edit_post and edit_user are capabilities used by this function to map to primitive capabilities that a user or role requires, such as edit_posts and edit_others_posts. Example usage: map_meta_cap( 'edit_posts', $user->ID );
map_meta_cap( 'edit_post', $user->ID, $post->ID );
map_meta_cap( 'edit_post_meta', $user->ID, $post->ID, $meta_key ); This function does not check whether the user has the required capabilities, it just returns what the required capabilities are.Parameters
$capstring- Capability being checked.
$user_idint- User ID.
$argsmixed- Optional further parameters, typically starting with an object ID.
Return
string[]- Primitive capabilities required of the user.
Hooks fired · 4
4 hooks fire while map_meta_cap() runs, in this order:
- apply_filters( auth_{$object_type}_meta_{$meta_key}_for_{$object_subtype} )filterline 491 (+446 into the body)
Filters whether the user is allowed to edit a specific meta key of a specific object type and subtype.
- apply_filters( auth_{$object_type}_meta_{$meta_key} )filterline 512 (+467 into the body)
Filters whether the user is allowed to edit a specific meta key of a specific object type.
- do_action( auth_{$object_type}_{$object_subtype}_meta_{$meta_key} )filter_deprecatedline 538 (+493 into the body)
Filters whether the user is allowed to edit meta for specific object types/subtypes.
- apply_filters( map_meta_cap )filterline 876 (+831 into the body)
Filters the primitive capabilities required of the given user to satisfy the capability being checked.
Uses · 24
- is_super_admin()Determines whether user is a site admin.
- is_multisite()Determines whether Multisite is enabled.
- user_can()Returns whether a particular user has the specified capability.
- __()Retrieves the translation of $text.
- _doing_it_wrong()Marks something as being incorrectly called.
- get_post()Retrieves post data given a post ID or post object.
- get_option()Retrieves an option value based on an option name.
- get_post_type_object()Retrieves a post type object by name.
- get_post_meta()Retrieves a post meta field for the given post ID.
- map_meta_cap()Maps a capability to the primitive capabilities required of the given user to satisfy the capability being checked.
- get_post_status_object()Retrieves a post status object by name.
- get_post_status()Retrieves the post status based on the post ID.
Show all 24
- get_object_subtype()Returns the object subtype for a given object ID of a specific type.
- is_protected_meta()Determines whether a meta key is considered protected.
- has_filter()Checks if any filter has been registered for a hook.
- apply_filters()Calls the callback functions that have been added to a filter hook.
- apply_filters_deprecated()Fires functions attached to a deprecated filter hook.
- get_comment()Retrieves comment data given a comment ID or comment object.
- wp_is_file_mod_allowed()Determines whether file modifications are allowed.
- get_site_option()Retrieve an option value for the current network based on name of option.
- get_term()Gets all term data from database by term ID.
- is_wp_error()Checks whether the given variable is a WordPress Error.
- get_taxonomy()Retrieves the taxonomy object of $taxonomy.
- get_post_type_capabilities()Builds an object with all post type capabilities out of a post type object
Used by · 3
- WP_Customize_Manager::grant_edit_post_capability_for_changeset()Re-maps 'edit_post' meta cap for a customize_changeset post to be the same as 'customize' maps.
- WP_User::has_cap()Returns whether the user has the specified capability.
- map_meta_cap()Maps a capability to the primitive capabilities required of the given user to satisfy the capability being checked.
Source
function map_meta_cap( $cap, $user_id, ...$args ) { $caps = array(); switch ( $cap ) { case 'remove_user': // In multisite the user must be a super admin to remove themselves. if ( isset( $args[0] ) && $user_id === (int) $args[0] && ! is_super_admin( $user_id ) ) { $caps[] = 'do_not_allow'; } else { $caps[] = 'remove_users'; } break; case 'promote_user': case 'add_users': $caps[] = 'promote_users'; break; case 'edit_user': case 'edit_users': // Allow user to edit themselves. if ( 'edit_user' === $cap && isset( $args[0] ) && $user_id === (int) $args[0] ) { break; } // In multisite the user must have manage_network_users caps. If editing a super admin, the user must be a super admin. if ( is_multisite() && ( ( ! is_super_admin( $user_id ) && 'edit_user' === $cap && is_super_admin( $args[0] ) ) || ! user_can( $user_id, 'manage_network_users' ) ) ) { $caps[] = 'do_not_allow'; } else { $caps[] = 'edit_users'; // edit_user maps to edit_users. } break; case 'delete_post': case 'delete_page': if ( ! isset( $args[0] ) ) { if ( 'delete_post' === $cap ) { /* translators: %s: Capability name. */ $message = __( 'When checking for the %s capability, you must always check it against a specific post.' ); } else { /* translators: %s: Capability name. */ $message = __( 'When checking for the %s capability, you must always check it against a specific page.' ); } _doing_it_wrong( __FUNCTION__, sprintf( $message, '<code>' . $cap . '</code>' ), '6.1.0' ); $caps[] = 'do_not_allow'; break; } $post = get_post( $args[0] ); if ( ! $post ) { $caps[] = 'do_not_allow'; break; } if ( 'revision' === $post->post_type ) { $caps[] = 'do_not_allow'; break; } if ( (int) get_option( 'page_for_posts' ) === $post->ID || (int) get_option( 'page_on_front' ) === $post->ID ) { $caps[] = 'manage_options'; break; } $post_type = get_post_type_object( $post->post_type ); if ( ! $post_type ) { /* translators: 1: Post type, 2: Capability name. */ $message = __( 'The post type %1$s is not registered, so it may not be reliable to check the capability %2$s against a post of that type.' ); _doing_it_wrong( __FUNCTION__, sprintf( $message, '<code>' . $post->post_type . '</code>', '<code>' . $cap . '</code>'History
Introduced in 2.0.0. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
6.7.0
Added the
edit_block_binding capability.from the docblock5.7.0
Added the
create_app_password, list_app_passwords, read_app_password, edit_app_password, delete_app_passwords, delete_app_password, and update_https capabilities.from the docblock5.3.0
Formalized the existing and already documented
...$args parameter by adding it to the function signature.from the docblock5.2.0
Added the
resume_plugin and resume_theme capabilities.from the docblock5.1.0
Added the
update_php capability.from the docblock4.9.6
Added the
export_others_personal_data, erase_others_personal_data, and manage_privacy_options capabilities.from the docblock2.0.0
Introduced.from the docblock
About this page
- Parsed data
- Generated from the wordpress-develop 6.7.7 tag, from
src/wp-includes/capabilities.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it. - Corrections
- Something wrong on this page? Report it and it gets fixed in the next regeneration.