W3cubDocs

/WordPress

WP_User::set_role( string $role )

Set the role of the user.

Description

This will remove the previous roles of the user and assign the user the new one. You can set the role to an empty string and it will remove all of the roles from the user.

Parameters

$role

(string) (Required) Role name.

Source

File: wp-includes/class-wp-user.php 

public function set_role( $role ) {
		if ( 1 === count( $this->roles ) && current( $this->roles ) == $role ) {
			return;
		}

		foreach ( (array) $this->roles as $oldrole ) {
			unset( $this->caps[ $oldrole ] );
		}

		$old_roles = $this->roles;
		if ( ! empty( $role ) ) {
			$this->caps[ $role ] = true;
			$this->roles         = array( $role => true );
		} else {
			$this->roles = false;
		}
		update_user_meta( $this->ID, $this->cap_key, $this->caps );
		$this->get_role_caps();
		$this->update_user_level_from_caps();

		/**
		 * Fires after the user's role has changed.
		 *
		 * @since 2.9.0
		 * @since 3.6.0 Added $old_roles to include an array of the user's previous roles.
		 *
		 * @param int      $user_id   The user ID.
		 * @param string   $role      The new role.
		 * @param string[] $old_roles An array of the user's previous roles.
		 */
		do_action( 'set_user_role', $this->ID, $role, $old_roles );
	}

Uses

Uses Description
wp-includes/class-wp-user.php: WP_User::update_user_level_from_caps()

Update the maximum user level for the user.
wp-includes/class-wp-user.php: WP_User::get_role_caps()

Retrieves all of the capabilities of the user’s roles, and merges them with individual user capabilities.
wp-includes/class-wp-user.php: set_user_role

Fires after the user’s role has changed.
wp-includes/plugin.php: do_action()

Execute functions hooked on a specific action hook.
wp-includes/user.php: update_user_meta()

Update user meta field based on user ID.

Changelog

Version Description
2.0.0 Introduced.

© 2003–2019 WordPress Foundation
Licensed under the GNU GPLv2+ License.
https://developer.wordpress.org/reference/classes/wp_user/set_role