get_editable_roles() – Function | Developer.WordPress.org

Fetch a filtered list of user roles that the current user is allowed to edit.

Description

Simple function whose main purpose is to allow filtering of the list of roles in the $wp_roles object so that plugins can remove inappropriate ones depending on the situation or user making edits.
Specifically because without filtering anyone with the edit_users capability can edit others to be administrators, even if they are only editors or authors. This filter allows admins to delegate user management.

Return

array[] Array of arrays containing role information.

More Information

Which roles a user can assign are determined by passing all roles through the editable_roles filter.
The file that defines this function (wp-admin/includes/user.php) is only loaded in the admin sections.

Source

function get_editable_roles() {
	$all_roles = wp_roles()->roles;

	/**
	 * Filters the list of editable roles.
	 *
	 * @since 2.8.0
	 *
	 * @param array[] $all_roles Array of arrays containing role information.
	 */
	$editable_roles = apply_filters( 'editable_roles', $all_roles );

	return $editable_roles;
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘editable_roles’, array[] $all_roles ): Filters the list of editable roles.

Uses	Description
wp_roles()`wp-includes/capabilities.php`	Retrieves the global WP_Roles instance and instantiates it if necessary.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.

Used by	Description
wp_ensure_editable_role()`wp-admin/includes/ms.php`	Stop execution if the role can not be assigned by the current user.
WP_REST_Users_Controller::check_role_update()`wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php`	Determines if the current user is allowed to make the desired roles change.
edit_user()`wp-admin/includes/user.php`	Edit user settings based on contents of $_POST
wp_dropdown_roles()`wp-admin/includes/template.php`	Prints out option HTML elements for role selectors.
admin_created_user_email()`wp-admin/includes/user.php`

Changelog

Version	Description
2.8.0	Introduced.

User Contributed Notes

Codex 9 years ago

Example

Currently, you can assign the following roles:

<dl>
  <?php foreach (get_editable_roles() as $role_name => $role_info): ?>
    <dt><?php echo $role_name ?></dt>
    <dd>
      <ul>
        <?php foreach ($role_info['capabilities'] as $capability => $_): ?>
          <li><?php echo $capability ?></li>
        <?php endforeach; ?>
      </ul>
    </dd>
  <?php endforeach; ?>
</dl>

get_editable_roles(): array[]

In this article