Changeset 54213 for trunk/src/wp-includes/class-wp-roles.php

Timestamp:

09/19/2022 08:47:22 PM (2 years ago)

Author:

davidbaumwald

Message:

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.

File:

• trunk/src/wp-includes/class-wp-roles.php (modified) (1 diff)

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

@@ -174 +174 @@
 
     /**
+     * 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.
      *