feat: adds support for versioning abilities

Author: JasonTheAdams

src/wp-includes/abilities-api/class-wp-abilities-registry.php

@@ -44,8 +44,8 @@ final class WP_Abilities_Registry {
 	 * @see wp_register_ability()
 	 *
 	 * @param string               $name The name of the ability. The name must be a string containing a namespace
-	 *                                   prefix, i.e. `my-plugin/my-ability`. It can only contain lowercase
-	 *                                   alphanumeric characters, dashes and the forward slash.
+	 *                                   prefix, i.e. `my-plugin/my-ability` or `my-plugin/v1/my-ability`. It can
+	 *                                   only contain lowercase alphanumeric characters, dashes and the forward slash.
 	 * @param array<string, mixed> $args {
 	 *     An associative array of arguments for the ability.
 	 *
@@ -78,11 +78,11 @@ final class WP_Abilities_Registry {
 	 * @return WP_Ability|null The registered ability instance on success, null on failure.
 	 */
 	public function register( string $name, array $args ): ?WP_Ability {
-		if ( ! preg_match( '/^[a-z0-9-]+\/[a-z0-9-]+$/', $name ) ) {
+		if ( ! preg_match( '/^[a-z0-9-]+\/([a-z0-9-]+\/)?[a-z0-9-]+$/', $name ) ) {
 			_doing_it_wrong(
 				__METHOD__,
 				__(
-					'Ability name must be a string containing a namespace prefix, i.e. "my-plugin/my-ability". It can only contain lowercase alphanumeric characters, dashes and the forward slash.'
+					'Ability name must be a string containing a namespace prefix, i.e. "my-plugin/my-ability" or "my-plugin/v1/my-ability". It can only contain lowercase alphanumeric characters, dashes and the forward slash.'
 				),
 				'6.9.0'
 			);

tests/phpunit/tests/abilities-api/wpAbilitiesRegistry.php

@@ -134,6 +134,20 @@ public function test_register_invalid_uppercase_characters_in_name() {
 		$this->assertNull( $result );
 	}
 
+	/**
+	 * Should reject ability name with more than two slashes.
+	 *
+	 * @ticket 64098
+	 *
+	 * @covers WP_Abilities_Registry::register
+	 *
+	 * @expectedIncorrectUsage WP_Abilities_Registry::register
+	 */
+	public function test_register_invalid_too_many_slashes_in_name() {
+		$result = $this->registry->register( 'test/v1/extra/add-numbers', self::$test_ability_args );
+		$this->assertNull( $result );
+	}
+
 	/**
 	 * Should reject ability registration without a label.
 	 *
@@ -411,6 +425,23 @@ public function test_register_new_ability() {
 		);
 	}
 
+	/**
+	 * Should successfully register a new ability with a versioned name.
+	 *
+	 * @ticket 64098
+	 *
+	 * @covers WP_Abilities_Registry::register
+	 */
+	public function test_register_new_ability_with_versioned_name() {
+		$versioned_name = 'test/v1/add-numbers';
+		$result         = $this->registry->register( $versioned_name, self::$test_ability_args );
+
+		$this->assertEquals(
+			new WP_Ability( $versioned_name, self::$test_ability_args ),
+			$result
+		);
+	}
+
 	/**
 	 * Should return false for ability that's not registered.
 	 *