Commit 00e22cb1bc for wordpress.org

commit 00e22cb1bcfb5153e4bbcca3c95b83014e6d5db4
Author: John Blackbourn <johnbillion@git.wordpress.org>
Date:   Sun Jun 29 21:47:29 2025 +0000

    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
    Built from https://develop.svn.wordpress.org/trunk@60364


    git-svn-id: http://core.svn.wordpress.org/trunk@59700 1a063a9b-81f0-0310-95a4-ce76da25c4cd

diff --git a/wp-includes/capabilities.php b/wp-includes/capabilities.php
index 48586e093c..2464ef5a79 100644
--- a/wp-includes/capabilities.php
+++ b/wp-includes/capabilities.php
@@ -1096,12 +1096,34 @@ function get_role( $role ) {
 /**
  * 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
+ * @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 bool[] $capabilities List of capabilities keyed by the capability name,
- *                             e.g. array( 'edit_posts' => true, 'delete_posts' => false ).
+ * @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.
  */
 function add_role( $role, $display_name, $capabilities = array() ) {
diff --git a/wp-includes/class-wp-roles.php b/wp-includes/class-wp-roles.php
index 95e08e6dc7..0b94e0f959 100644
--- a/wp-includes/class-wp-roles.php
+++ b/wp-includes/class-wp-roles.php
@@ -143,16 +143,34 @@ class WP_Roles {
 	 *
 	 * 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.
+	 * 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 bool[] $capabilities Optional. List of capabilities keyed by the capability name,
-	 *                             e.g. `array( 'edit_posts' => true, 'delete_posts' => false )`.
-	 *                             Default empty 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.
 	 */
 	public function add_role( $role, $display_name, $capabilities = array() ) {
@@ -160,6 +178,10 @@ class WP_Roles {
 			return;
 		}

+		if ( wp_is_numeric_array( $capabilities ) ) {
+			$capabilities = array_fill_keys( $capabilities, true );
+		}
+
 		$this->roles[ $role ] = array(
 			'name'         => $display_name,
 			'capabilities' => $capabilities,
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 03df73ad63..673714ba1e 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '6.9-alpha-60363';
+$wp_version = '6.9-alpha-60364';

 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.