Using WordPress ‘editable_roles’ PHP filter

The editable_roles WordPress PHP filter allows you to modify the list of roles that a user with the ‘edit_users’ capability can assign to others.

Usage

add_filter('editable_roles', 'my_custom_editable_roles');

function my_custom_editable_roles($all_roles) {
    // your custom code here
    return $all_roles;
}

Parameters

• $all_roles (array[]) – An array of arrays containing role information.

More information

See WordPress Developer Resources: editable_roles

This filter is applied by the get_editable_roles() function to the list of roles that one user can assign to others. It is displayed in the bulk operations of the Users Screen and on the profile screen, if the user has the ‘list_users’ and ‘promote_users’ capabilities.

Examples

Remove a specific role from the list of editable roles

This example removes the ‘Administrator’ role from the list of editable roles.

add_filter('editable_roles', 'remove_admin_from_editable_roles');

function remove_admin_from_editable_roles($all_roles) {
    unset($all_roles['administrator']);
    return $all_roles;
}

Allow only specific roles to be assigned

This example allows only the ‘Subscriber’ and ‘Contributor’ roles to be assigned.

add_filter('editable_roles', 'allow_specific_editable_roles');

function allow_specific_editable_roles($all_roles) {
    $allowed_roles = ['subscriber', 'contributor'];
    foreach ($all_roles as $role => $details) {
        if (!in_array($role, $allowed_roles)) {
            unset($all_roles[$role]);
        }
    }
    return $all_roles;
}

Add a custom role to the list of editable roles

This example adds a custom role called ‘custom_role’ to the list of editable roles.

add_filter('editable_roles', 'add_custom_role_to_editable_roles');

function add_custom_role_to_editable_roles($all_roles) {
    $all_roles['custom_role'] = [
        'name' => 'Custom Role',
        'capabilities' => ['read' => true],
    ];
    return $all_roles;
}

Remove all roles except the current user’s role

This example removes all roles from the list of editable roles except for the current user’s role.

add_filter('editable_roles', 'remove_roles_except_current_user_role');

function remove_roles_except_current_user_role($all_roles) {
    $current_user = wp_get_current_user();
    $current_role = $current_user->roles[0];

    foreach ($all_roles as $role => $details) {
        if ($role !== $current_role) {
            unset($all_roles[$role]);
        }
    }
    return $all_roles;
}

Dynamically change editable roles based on user’s role

This example allows users with the ‘Editor’ role to only assign the ‘Subscriber’ role, while ‘Administrators’ can assign all roles.

add_filter('editable_roles', 'dynamic_editable_roles_based_on_user_role');

function dynamic_editable_roles_based_on_user_role($all_roles) {
    $current_user = wp_get_current_user();

    if (in_array('editor', $current_user->roles)) {
        return ['subscriber' => $all_roles['subscriber']];
    } elseif (in_array('administrator', $current_user->roles)) {
        return $all_roles;
    } else {
        return [];
    }
}