Role/Capability: Add a new update_role function.

Until now, changing a user's role involved deleting a user's role then re-adding.  This change creates a new `update_role` function and associated method in `WP_Roles` to consolidate this process.

This commit also introduces new unit tests around `update_role` and adds additional "unhappy path" tests for roles and capabilities in general.

Props maksimkuzmin, peterwilsoncc, NomNom99, costdev, SergeyBiryukov.
Fixes #54572.

git-svn-id: https://develop.svn.wordpress.org/trunk@54213 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-includes/capabilities.php

@@ -1030,6 +1030,30 @@ function add_role( $role, $display_name, $capabilities = array() ) {
 	return wp_roles()->add_role( $role, $display_name, $capabilities );
 }
 
+/**
+ * Updates an existing role. Creates a new role if it doesn't exist.
+ *
+ * Modifies the display name and/or capabilities for an existing role.
+ * If the role does not exist then a new role is created.
+ *
+ * The capabilities are defined in the following format: `array( 'read' => true )`.
+ * To explicitly deny the role a capability, set the value for that capability to false.
+ *
+ * @since 6.1.0
+ *
+ * @param string      $role         Role name.
+ * @param string|null $display_name Optional. Role display name. If null, the display name
+ *                                  is not modified. Default null.
+ * @param bool[]|null $capabilities Optional. List of capabilities keyed by the capability name,
+ *                                  e.g. `array( 'edit_posts' => true, 'delete_posts' => false )`.
+ *                                  If null, don't alter capabilities for the existing role and make
+ *                                  empty capabilities for the new one. Default null.
+ * @return WP_Role|void WP_Role object, if the role is updated.
+ */
+function update_role( $role, $display_name = null, $capabilities = null ) {
+	return wp_roles()->update_role( $role, $display_name, $capabilities );
+}
+
 /**
  * Removes a role, if it exists.
  *

src/wp-includes/class-wp-roles.php

@@ -172,6 +172,76 @@ public function add_role( $role, $display_name, $capabilities = array() ) {
 		return $this->role_objects[ $role ];
 	}
 
+	/**
+	 * Updates an existing role. Creates a new role if it doesn't exist.
+	 *
+	 * Modifies the display name and/or capabilities for an existing role.
+	 * If the role does not exist then a new role is created.
+	 *
+	 * The capabilities are defined in the following format: `array( 'read' => true )`.
+	 * To explicitly deny the role a capability, set the value for that capability to false.
+	 *
+	 * @since 6.1.0
+	 *
+	 * @param string      $role         Role name.
+	 * @param string|null $display_name Optional. Role display name. If null, the display name
+	 *                                  is not modified. Default null.
+	 * @param bool[]|null $capabilities Optional. List of capabilities keyed by the capability name,
+	 *                                  e.g. `array( 'edit_posts' => true, 'delete_posts' => false )`.
+	 *                                  If null, don't alter capabilities for the existing role and make
+	 *                                  empty capabilities for the new one. Default null.
+	 * @return WP_Role|void WP_Role object, if the role is updated.
+	 */
+	public function update_role( $role, $display_name = null, $capabilities = null ) {
+		if ( ! is_string( $role ) || '' === trim( $role ) ) {
+			return;
+		}
+
+		if ( null !== $display_name && ( ! is_string( $display_name ) || '' === trim( $display_name ) ) ) {
+			return;
+		}
+
+		if ( null !== $capabilities && ! is_array( $capabilities ) ) {
+			return;
+		}
+
+		if ( null === $display_name && null === $capabilities ) {
+			if ( isset( $this->role_objects[ $role ] ) ) {
+				return $this->role_objects[ $role ];
+			}
+			return;
+		}
+
+		if ( null === $display_name ) {
+			if ( ! isset( $this->role_objects[ $role ] ) ) {
+				return;
+			}
+
+			$display_name = $this->roles[ $role ]['name'];
+		}
+
+		if ( null === $capabilities ) {
+			if ( isset( $this->role_objects[ $role ] ) ) {
+				$capabilities = $this->role_objects[ $role ]->capabilities;
+			} else {
+				$capabilities = array();
+			}
+		}
+
+		if ( isset( $this->roles[ $role ] ) ) {
+			if ( null === $capabilities ) {
+				$capabilities = $this->role_objects[ $role ]->capabilities;
+			}
+
+			unset( $this->role_objects[ $role ] );
+			unset( $this->role_names[ $role ] );
+			unset( $this->roles[ $role ] );
+		}
+
+		// The roles database option will be updated in ::add_role().
+		return $this->add_role( $role, $display_name, $capabilities );
+	}
+
 	/**
 	 * Removes a role by name.
 	 *