[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

Search

title

Body

[close]

/wp-includes/ -> capabilities.php (summary)

Core User Role & Capabilities API

File Size: 1090 lines (36 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 16 functions

  map_meta_cap()
  current_user_can()
  current_user_can_for_blog()
  author_can()
  user_can()
  wp_roles()
  get_role()
  add_role()
  remove_role()
  get_super_admins()
  is_super_admin()
  grant_super_admin()
  revoke_super_admin()
  wp_maybe_grant_install_languages_cap()
  wp_maybe_grant_resume_extensions_caps()
  wp_maybe_grant_site_health_caps()

Functions
Functions that are not part of a class:

map_meta_cap( $cap, $user_id, ...$args )   X-Ref
Maps a capability to the primitive capabilities required of the given user to
satisfy the capability being checked.

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.

return: string[] Primitive capabilities required of the user.
param: string $cap     Capability being checked.
param: int    $user_id User ID.
param: mixed  ...$args Optional further parameters, typically starting with an object ID.

current_user_can( $capability, ...$args )   X-Ref
Returns whether the current user has the specified capability.

This function also accepts an ID of an object to check against if the capability is a meta capability. Meta
capabilities such as `edit_post` and `edit_user` are capabilities used by the `map_meta_cap()` function to
map to primitive capabilities that a user or role has, such as `edit_posts` and `edit_others_posts`.

Example usage:

current_user_can( 'edit_posts' );
current_user_can( 'edit_post', $post->ID );
current_user_can( 'edit_post_meta', $post->ID, $meta_key );

While checking against particular roles in place of a capability is supported
in part, this practice is discouraged as it may produce unreliable results.

Note: Will always return true if the current user is a super admin, unless specifically denied.

return: bool Whether the current user has the given capability. If `$capability` is a meta cap and `$object_id` is
param: string $capability Capability name.
param: mixed  ...$args    Optional further parameters, typically starting with an object ID.

current_user_can_for_blog( $blog_id, $capability, ...$args )   X-Ref
Returns whether the current user has the specified capability for a given site.

This function also accepts an ID of an object to check against if the capability is a meta capability. Meta
capabilities such as `edit_post` and `edit_user` are capabilities used by the `map_meta_cap()` function to
map to primitive capabilities that a user or role has, such as `edit_posts` and `edit_others_posts`.

Example usage:

current_user_can_for_blog( $blog_id, 'edit_posts' );
current_user_can_for_blog( $blog_id, 'edit_post', $post->ID );
current_user_can_for_blog( $blog_id, 'edit_post_meta', $post->ID, $meta_key );

return: bool Whether the user has the given capability.
param: int    $blog_id    Site ID.
param: string $capability Capability name.
param: mixed  ...$args    Optional further parameters, typically starting with an object ID.

author_can( $post, $capability, ...$args )   X-Ref
Returns whether the author of the supplied post has the specified capability.

This function also accepts an ID of an object to check against if the capability is a meta capability. Meta
capabilities such as `edit_post` and `edit_user` are capabilities used by the `map_meta_cap()` function to
map to primitive capabilities that a user or role has, such as `edit_posts` and `edit_others_posts`.

Example usage:

author_can( $post, 'edit_posts' );
author_can( $post, 'edit_post', $post->ID );
author_can( $post, 'edit_post_meta', $post->ID, $meta_key );

return: bool Whether the post author has the given capability.
param: int|WP_Post $post       Post ID or post object.
param: string      $capability Capability name.
param: mixed       ...$args    Optional further parameters, typically starting with an object ID.

user_can( $user, $capability, ...$args )   X-Ref
Returns whether a particular user has the specified capability.

This function also accepts an ID of an object to check against if the capability is a meta capability. Meta
capabilities such as `edit_post` and `edit_user` are capabilities used by the `map_meta_cap()` function to
map to primitive capabilities that a user or role has, such as `edit_posts` and `edit_others_posts`.

Example usage:

user_can( $user->ID, 'edit_posts' );
user_can( $user->ID, 'edit_post', $post->ID );
user_can( $user->ID, 'edit_post_meta', $post->ID, $meta_key );

return: bool Whether the user has the given capability.
param: int|WP_User $user       User ID or object.
param: string      $capability Capability name.
param: mixed       ...$args    Optional further parameters, typically starting with an object ID.

wp_roles()   X-Ref
Retrieves the global WP_Roles instance and instantiates it if necessary.

return: WP_Roles WP_Roles global instance if not already instantiated.

get_role( $role )   X-Ref
Retrieve role object.

return: WP_Role|null WP_Role object if found, null if the role does not exist.
param: string $role Role name.

add_role( $role, $display_name, $capabilities = array()   X-Ref
Add role, if it does not exist.

return: WP_Role|null WP_Role object if role is added, null if already exists.
param: string $role         Role name.
param: string $display_name Display name for role.
param: bool[] $capabilities List of capabilities keyed by the capability name,

remove_role( $role )   X-Ref
Remove role, if it exists.

param: string $role Role name.

get_super_admins()   X-Ref
Retrieve a list of super admins.

return: string[] List of super admin logins.

is_super_admin( $user_id = false )   X-Ref
Determine if user is a site admin.

return: bool Whether the user is a site admin.
param: int|false $user_id Optional. The ID of a user. Defaults to false, to check the current user.

grant_super_admin( $user_id )   X-Ref
Grants Super Admin privileges.

return: bool True on success, false on failure. This can fail when the user is
param: int $user_id ID of the user to be granted Super Admin privileges.

revoke_super_admin( $user_id )   X-Ref
Revokes Super Admin privileges.

return: bool True on success, false on failure. This can fail when the user's email
param: int $user_id ID of the user Super Admin privileges to be revoked from.

wp_maybe_grant_install_languages_cap( $allcaps )   X-Ref
Filters the user capabilities to grant the 'install_languages' capability as necessary.

A user must have at least one out of the 'update_core', 'install_plugins', and
'install_themes' capabilities to qualify for 'install_languages'.

return: bool[] Filtered array of the user's capabilities.
param: bool[] $allcaps An array of all the user's capabilities.

wp_maybe_grant_resume_extensions_caps( $allcaps )   X-Ref
Filters the user capabilities to grant the 'resume_plugins' and 'resume_themes' capabilities as necessary.

return: bool[] Filtered array of the user's capabilities.
param: bool[] $allcaps An array of all the user's capabilities.

wp_maybe_grant_site_health_caps( $allcaps, $caps, $args, $user )   X-Ref
Filters the user capabilities to grant the 'view_site_health_checks' capabilities as necessary.

return: bool[] Filtered array of the user's capabilities.
param: bool[]   $allcaps An array of all the user's capabilities.
param: string[] $caps    Required primitive capabilities for the requested capability.
param: array    $args {
param: WP_User  $user    The user object.



Generated : Wed Sep 22 08:20:01 2021 Cross-referenced by PHPXref