Changeset 60364

Timestamp:

06/29/2025 09:45:30 PM (3 months ago)

Author:

johnbillion

Message:

Role/Capability: Add support for passing a numerically-indexed array of capability names to the add_role() function and the WP_Roles::add_role() method.

Denying a capability at the point of creating the role is a relatively uncommon requirement, so this simplifies the syntax needed to grant a list of capabilities to the role.

Props eclev91, johnbillion, flixos90, johnjamesjacoby, soulseekah

Fixes #43421

Location:

trunk

Files:

• src/wp-includes/capabilities.php (modified) (1 diff)
• src/wp-includes/class-wp-roles.php (modified) (2 diffs)
• tests/phpunit/tests/user/capabilities.php (modified) (1 diff)

trunk/src/wp-includes/capabilities.php

@@ -1097 +1097 @@
  * Adds a role, if it does not exist.
  *
+ * The list of capabilities can be passed either as a numerically indexed array of capability names, or an
+ * associative array of boolean values keyed by the capability name. To explicitly deny the role a capability, set
+ * the value for that capability to false.
+ *
+ * Examples:
+ *
+ *     // Add a role that can edit posts.
+ *     add_role( 'custom_role', 'Custom Role', array(
+ *         'read',
+ *         'edit_posts',
+ *     ) );
+ *
+ * Or, using an associative array:
+ *
+ *     // Add a role that can edit posts but explicitly cannot not delete them.
+ *     add_role( 'custom_role', 'Custom Role', array(
+ *         'read' => true,
+ *         'edit_posts' => true,
+ *         'delete_posts' => false,
+ *     ) );
+ *
  * @since 2.0.0
- *
- * @param string $role         Role name.
- * @param string $display_name Display name for role.
- * @param bool[] $capabilities List of capabilities keyed by the capability name,
- *                             e.g. array( 'edit_posts' => true, 'delete_posts' => false ).
+ * @since x.y.z Support was added for a numerically indexed array of strings for the capabilities array.
+ *
+ * @param string                               $role         Role name.
+ * @param string                               $display_name Display name for role.
+ * @param array<string,bool>|array<int,string> $capabilities Capabilities to be added to the role.
+ *                                                           Default empty array.
  * @return WP_Role|void WP_Role object, if the role is added.
  */

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

@@ -144 +144 @@
      * Updates the list of roles, if the role doesn't already exist.
      *
-     * 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 2.0.0
-     *
-     * @param string $role         Role name.
-     * @param string $display_name Role display name.
-     * @param bool[] $capabilities Optional. List of capabilities keyed by the capability name,
-     *                             e.g. `array( 'edit_posts' => true, 'delete_posts' => false )`.
-     *                             Default empty array.
+     * The list of capabilities can be passed either as a numerically indexed array of capability names, or an
+     * associative array of boolean values keyed by the capability name. To explicitly deny the role a capability, set
+     * the value for that capability to false.
+     *
+     * Examples:
+     *
+     *     // Add a role that can edit posts.
+     *     wp_roles()->add_role( 'custom_role', 'Custom Role', array(
+     *         'read',
+     *         'edit_posts',
+     *     ) );
+     *
+     * Or, using an associative array:
+     *
+     *     // Add a role that can edit posts but explicitly cannot not delete them.
+     *     wp_roles()->add_role( 'custom_role', 'Custom Role', array(
+     *         'read' => true,
+     *         'edit_posts' => true,
+     *         'delete_posts' => false,
+     *     ) );
+     *
+     * @since 2.0.0
+     * @since x.y.z Support was added for a numerically indexed array of strings for the capabilities array.
+     *
+     * @param string                               $role         Role name.
+     * @param string                               $display_name Role display name.
+     * @param array<string,bool>|array<int,string> $capabilities Capabilities to be added to the role.
+     *                                                           Default empty array.
      * @return WP_Role|void WP_Role object, if the role is added.
      */
@@ -159 +177 @@
         if ( empty( $role ) || isset( $this->roles[ $role ] ) ) {
             return;
+        }
+
+        if ( wp_is_numeric_array( $capabilities ) ) {
+            $capabilities = array_fill_keys( $capabilities, true );
         }
 

trunk/tests/phpunit/tests/user/capabilities.php

@@ -994 +994 @@
 
     /**
+     * Test add_role with implied capabilities grant successfully grants capabilities.
+     *
+     * @ticket 43421
+     */
+    public function test_add_role_with_single_level_capabilities() {
+        $role_name = 'janitor';
+        add_role(
+            $role_name,
+            'Janitor',
+            array(
+                'foo',
+            )
+        );
+        $this->flush_roles();
+
+        // Assign a user to that role.
+        $id   = self::factory()->user->create( array( 'role' => $role_name ) );
+        $user = new WP_User( $id );
+
+        $this->assertTrue( $user->has_cap( 'foo' ) );
+    }
+
+    /**
      * Change the capabilities associated with a role and make sure the change
      * is reflected in has_cap().