[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

title

Body

[close]

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

Core User Role & Capabilities API

File Size: 1065 lines (34 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 )   X-Ref
Maps meta capabilities to primitive capabilities.

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 has, 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 does not actually compare whether the user ID has the actual capability,
just what the capability or capabilities are. Meta capability list value can
be 'delete_user', 'edit_user', 'remove_user', 'promote_user', 'delete_post',
'delete_page', 'edit_post', 'edit_page', 'read_post', or 'read_page'.

return: array Actual capabilities for meta capability.
param: string $cap     Capability name.
param: int    $user_id User ID.
param: mixed  ...$args Optional further parameters, typically starting with an object ID.

current_user_can( $capability )   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 )   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 )   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 )   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: array $capabilities List of capabilities, e.g. array( 'edit_posts' => true, 'delete_posts' => false );

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: array List of super admin logins

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

return: bool True if the user is a site admin.
param: int $user_id (Optional) The ID of a user. Defaults to 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: Tue Jun 18 08:20:01 2019 Cross-referenced by PHPXref 0.7