This hook is applied to a user's capabilities list in the WP_User->has_cap function (which is called by the current_user_can() function). Filter function arguments are the capabilities list to be filtered, the capability being questioned, and the argument list (which has things such as the post ID if the capability is to edit posts, etc.). Changing a user's capabilities can, for example, enable or restrict access to specific administration panels.
function give_permissions( $allcaps, $cap, $args ) {
// give author some permissions
}
add_filter( 'user_has_cap', 'give_permissions', 10, 3 );
A Full Example:
/**
* author_cap_filter()
*
* Filter on the current_user_can() function.
* This function is used to explicitly allow authors to edit contributors and other
* authors posts if they are published or pending.
*
* @param array $allcaps All the capabilities of the user
* @param array $cap [0] Required capability
* @param array $args [0] Requested capability
* [1] User ID
* [2] Associated object ID
*/
function author_cap_filter( $allcaps, $cap, $args ) {
// Bail out if we're not asking about a post:
if ( 'edit_post' != $args[0] )
return $allcaps;
// Bail out for users who can already edit others posts:
if ( $allcaps['edit_others_posts'] )
return $allcaps;
// Bail out for users who can't publish posts:
if ( !isset( $allcaps['publish_posts'] ) or !$allcaps['publish_posts'] )
return $allcaps;
// Load the post data:
$post = get_post( $args[2] );
// Bail out if the user is the post author:
if ( $args[1] == $post->post_author )
return $allcaps;
// Bail out if the post isn't pending or published:
if ( ( 'pending' != $post->post_status ) and ( 'publish' != $post->post_status ) )
return $allcaps;
// Load the author data:
$author = new WP_User( $post->post_author );
// Bail out if post author can edit others posts:
if ( $author->has_cap( 'edit_others_posts' ) )
return $allcaps;
$allcaps[$cap[0]] = true;
return $allcaps;
}
add_filter( 'user_has_cap', 'author_cap_filter', 10, 3 );
Passing in a numeric value to has_cap on WP_User objects has been deprecated. Passing a numeric value will generate a deprecated option warning if debugging mode is enabled via wp_config.php:
Usage of user levels by plugins and themes is deprecated. Use roles and capabilities instead.
This will occur if a plugin or a theme calls has_cap directly. The plugin or theme needs to be updated to use the new roles and capabilities classes.
It is important to note that many built-in functions will use the has_cap functionality within their implementation. For example add_options_page() calls has_cap on the 3rd parameter. If this is called with the Version 2.0 user level syntax by passing in a numeric value you will see the warning as noted above.
Return to Plugin API/Filter Reference