WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Function Reference/remove cap

Description

Removes a capability from a role or specific user. Changing the capabilities of a role or user is persistent, meaning the removed capability will stay in effect until explicitly granted.

Note: This is not a global function, but a method of the WP_Roles, WP_Role and WP_User classes. It must be called using an instance of one of these classes, as shown in the examples.

Note: This setting is saved to the database (in table wp_options, field 'wp_user_roles'), so you should run this only once, on theme/plugin activation and/or deactivation.

Usage

<?php 
  
global $wp_roles// global class wp-includes/capabilities.php
  
$wp_roles->remove_cap$role$cap ); 
?> 
or <?php
  $role 
get_role'author' );
  
$role->remove_cap$cap );
?> 

Parameters

$role
(string) (Required) role name
Default: None
$cap
(string) (Required) capability name
Default: None

Example

/**
 * Don't let editors read private posts.
 *
 * You should call the function when your plugin is activated.
 *
 * @uses WP_Role::remove_cap()
 */
function remove_editor_read_private_posts() {

	// get_role returns an instance of WP_Role.
	$role = get_role( 'editor' );
	$role->remove_cap( 'read_private_posts' );
}

/**
 * Don't let editors read private posts.
 *
 * An alternative using WP_Roles instead of WP_Role.
 *
 * You should call the function when your plugin is activated.
 *
 * @uses $wp_roles
 * @uses WP_Roles::remove_cap()
 */
function remove_editor_read_private_posts(){

	// $wp_roles is an instance of WP_Roles.
	global $wp_roles;
	$wp_roles->remove_cap( 'editor', 'read_private_posts' );
}
// Remove a capability from a specific user.
$user_id = // The ID of the user to remove the capability from.
$user = new WP_User( $user_id );
$user->remove_cap( 'read_private_posts' );

Remove multiple capabilities

/**
 * Remove capabilities from editors.
 *
 * Call the function when your plugin/theme is activated.
 */
function wpcodex_set_capabilities() {

    // Get the role object.
    $editor = get_role( 'editor' );

	// A list of capabilities to remove from editors.
    $caps = array(
        'moderate_comments',
        'manage_categories',
        'manage_links',
        'edit_others_posts',
        'edit_others_pages',
        'delete_posts',
    );

    foreach ( $caps as $cap ) {
    
        // Remove the capability.
        $editor->remove_cap( $cap );
    }
}
add_action( 'init', 'wpcodex_set_capabilities' );

Notes

  • remove_cap() is not a global function, it is a method available from the classes WP_Roles, WP_Role and WP_User, so it must be called from an instance of one of these classes as shown in the above examples.

Changelog

Source File

remove_cap() is located in wp-includes/capabilities.php.

Related

Roles and Capabilities:
See also index of Function Reference and index of Template Tags.