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

Timestamp:

06/29/2025 09:45:30 PM (14 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

File:

• trunk/src/wp-includes/class-wp-roles.php (modified) (2 diffs)

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 );
                 }