From c7f3e984563f2a010c410e3ee7e2e7229829003f Mon Sep 17 00:00:00 2001 From: Jorge Costa Date: Mon, 2 Feb 2026 13:58:14 +0000 Subject: [PATCH 1/3] Abilities API: Allow nested namespace ability names (2-4 segments) Expand ability name validation from exactly 2 segments (namespace/ability) to 2-4 segments, enabling names like my-plugin/resource/find and my-plugin/resource/sub/find. Update the validation regex, error messages, docblocks, and add corresponding unit and REST API tests. --- src/wp-includes/abilities-api.php | 14 ++-- .../class-wp-abilities-registry.php | 11 +-- .../abilities-api/class-wp-ability.php | 4 +- .../abilities-api/wpAbilitiesRegistry.php | 68 +++++++++++++++++++ .../wpRestAbilitiesV1RunController.php | 62 +++++++++++++++++ 5 files changed, 146 insertions(+), 13 deletions(-) diff --git a/src/wp-includes/abilities-api.php b/src/wp-includes/abilities-api.php index 73ba658f3f10d..ea070892fc785 100644 --- a/src/wp-includes/abilities-api.php +++ b/src/wp-includes/abilities-api.php @@ -132,7 +132,8 @@ * * Ability names must follow these rules: * - * - Include a namespace prefix (e.g., `my-plugin/my-ability`). + * - Contain 2 to 4 segments separated by forward slashes + * (e.g., `my-plugin/my-ability`, `my-plugin/resource/find`, `my-plugin/resource/sub/find`). * - Use only lowercase alphanumeric characters, dashes, and forward slashes. * - Use descriptive, action-oriented names (e.g., `process-payment`, `generate-report`). * @@ -225,8 +226,9 @@ * @see wp_register_ability_category() * @see wp_unregister_ability() * - * @param string $name The name of the ability. Must be a namespaced string containing - * a prefix, e.g., `my-plugin/my-ability`. Can only contain lowercase + * @param string $name The name of the ability. Must contain 2 to 4 segments separated + * by forward slashes, e.g., `my-plugin/my-ability` or + * `my-plugin/resource/my-ability`. Can only contain lowercase * alphanumeric characters, dashes, and forward slashes. * @param array $args { * An associative array of arguments for configuring the ability. @@ -318,7 +320,7 @@ function wp_register_ability( string $name, array $args ): ?WP_Ability { * @see wp_register_ability() * * @param string $name The name of the ability to unregister, including namespace prefix - * (e.g., 'my-plugin/my-ability'). + * (e.g., 'my-plugin/my-ability' or 'my-plugin/resource/find'). * @return WP_Ability|null The unregistered ability instance on success, `null` on failure. */ function wp_unregister_ability( string $name ): ?WP_Ability { @@ -351,7 +353,7 @@ function wp_unregister_ability( string $name ): ?WP_Ability { * @see wp_get_ability() * * @param string $name The name of the ability to check, including namespace prefix - * (e.g., 'my-plugin/my-ability'). + * (e.g., 'my-plugin/my-ability' or 'my-plugin/resource/find'). * @return bool `true` if the ability is registered, `false` otherwise. */ function wp_has_ability( string $name ): bool { @@ -383,7 +385,7 @@ function wp_has_ability( string $name ): bool { * @see wp_has_ability() * * @param string $name The name of the ability, including namespace prefix - * (e.g., 'my-plugin/my-ability'). + * (e.g., 'my-plugin/my-ability' or 'my-plugin/resource/find'). * @return WP_Ability|null The registered ability instance, or `null` if not registered. */ function wp_get_ability( string $name ): ?WP_Ability { diff --git a/src/wp-includes/abilities-api/class-wp-abilities-registry.php b/src/wp-includes/abilities-api/class-wp-abilities-registry.php index ecd6dc2785e70..297712d5f8dce 100644 --- a/src/wp-includes/abilities-api/class-wp-abilities-registry.php +++ b/src/wp-includes/abilities-api/class-wp-abilities-registry.php @@ -43,9 +43,10 @@ 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. + * @param string $name The name of the ability. The name must contain 2 to 4 segments + * separated by forward slashes, e.g. `my-plugin/my-ability` or + * `my-plugin/resource/my-ability`. It can only contain lowercase + * alphanumeric characters, dashes, and forward slashes. * @param array $args { * An associative array of arguments for the ability. * @@ -78,11 +79,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-]+){1,3}$/', $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 contain 2 to 4 segments separated by forward slashes, e.g. "my-plugin/my-ability" or "my-plugin/resource/my-ability". It can only contain lowercase alphanumeric characters, dashes, and forward slashes.' ), '6.9.0' ); diff --git a/src/wp-includes/abilities-api/class-wp-ability.php b/src/wp-includes/abilities-api/class-wp-ability.php index 967f1641156b0..bdcb8c0bd017a 100644 --- a/src/wp-includes/abilities-api/class-wp-ability.php +++ b/src/wp-includes/abilities-api/class-wp-ability.php @@ -52,7 +52,7 @@ class WP_Ability { /** * The name of the ability, with its namespace. - * Example: `my-plugin/my-ability`. + * Examples: `my-plugin/my-ability`, `my-plugin/resource/find`. * * @since 6.9.0 * @var string @@ -340,7 +340,7 @@ protected function prepare_properties( array $args ): array { /** * Retrieves the name of the ability, with its namespace. - * Example: `my-plugin/my-ability`. + * Examples: `my-plugin/my-ability`, `my-plugin/resource/find`. * * @since 6.9.0 * diff --git a/tests/phpunit/tests/abilities-api/wpAbilitiesRegistry.php b/tests/phpunit/tests/abilities-api/wpAbilitiesRegistry.php index 32479d69e2f8c..b9cc58279c118 100644 --- a/tests/phpunit/tests/abilities-api/wpAbilitiesRegistry.php +++ b/tests/phpunit/tests/abilities-api/wpAbilitiesRegistry.php @@ -136,6 +136,74 @@ public function test_register_invalid_uppercase_characters_in_name() { $this->assertNull( $result ); } + /** + * Should accept ability name with 3 segments (2 slashes). + * + * @ticket 64098 + * + * @covers WP_Abilities_Registry::register + */ + public function test_register_valid_name_with_three_segments() { + $result = $this->registry->register( 'test/sub/add-numbers', self::$test_ability_args ); + $this->assertInstanceOf( WP_Ability::class, $result ); + $this->assertSame( 'test/sub/add-numbers', $result->get_name() ); + } + + /** + * Should accept ability name with 4 segments (3 slashes). + * + * @ticket 64098 + * + * @covers WP_Abilities_Registry::register + */ + public function test_register_valid_name_with_four_segments() { + $result = $this->registry->register( 'test/sub/deep/add-numbers', self::$test_ability_args ); + $this->assertInstanceOf( WP_Ability::class, $result ); + $this->assertSame( 'test/sub/deep/add-numbers', $result->get_name() ); + } + + /** + * Should reject ability name with 5 segments (exceeds maximum of 4). + * + * @ticket 64098 + * + * @covers WP_Abilities_Registry::register + * + * @expectedIncorrectUsage WP_Abilities_Registry::register + */ + public function test_register_invalid_name_with_five_segments() { + $result = $this->registry->register( 'test/a/b/c/too-deep', self::$test_ability_args ); + $this->assertNull( $result ); + } + + /** + * Should reject ability name with empty segments (double slashes). + * + * @ticket 64098 + * + * @covers WP_Abilities_Registry::register + * + * @expectedIncorrectUsage WP_Abilities_Registry::register + */ + public function test_register_invalid_name_with_empty_segment() { + $result = $this->registry->register( 'test//add-numbers', self::$test_ability_args ); + $this->assertNull( $result ); + } + + /** + * Should reject ability name with trailing slash. + * + * @ticket 64098 + * + * @covers WP_Abilities_Registry::register + * + * @expectedIncorrectUsage WP_Abilities_Registry::register + */ + public function test_register_invalid_name_with_trailing_slash() { + $result = $this->registry->register( 'test/add-numbers/', self::$test_ability_args ); + $this->assertNull( $result ); + } + /** * Should reject ability registration without a label. * diff --git a/tests/phpunit/tests/rest-api/wpRestAbilitiesV1RunController.php b/tests/phpunit/tests/rest-api/wpRestAbilitiesV1RunController.php index bccc30c2f2e94..0c03d72dab8a5 100644 --- a/tests/phpunit/tests/rest-api/wpRestAbilitiesV1RunController.php +++ b/tests/phpunit/tests/rest-api/wpRestAbilitiesV1RunController.php @@ -379,6 +379,43 @@ private function register_test_abilities(): void { ) ); + // Ability with nested namespace (3 segments). + $this->register_test_ability( + 'test/math/add', + array( + 'label' => 'Nested Add', + 'description' => 'Adds numbers with nested namespace', + 'category' => 'math', + 'input_schema' => array( + 'type' => 'object', + 'properties' => array( + 'a' => array( + 'type' => 'number', + 'description' => 'First number', + ), + 'b' => array( + 'type' => 'number', + 'description' => 'Second number', + ), + ), + 'required' => array( 'a', 'b' ), + 'additionalProperties' => false, + ), + 'output_schema' => array( + 'type' => 'number', + ), + 'execute_callback' => static function ( array $input ) { + return $input['a'] + $input['b']; + }, + 'permission_callback' => static function () { + return current_user_can( 'edit_posts' ); + }, + 'meta' => array( + 'show_in_rest' => true, + ), + ) + ); + // Read-only ability for query params testing. $this->register_test_ability( 'test/query-params', @@ -432,6 +469,31 @@ public function test_execute_regular_ability_post(): void { $this->assertEquals( 8, $response->get_data() ); } + /** + * Test executing an ability with a nested namespace (3 segments) via REST. + * + * @ticket 64098 + */ + public function test_execute_nested_namespace_ability(): void { + $request = new WP_REST_Request( 'POST', '/wp-abilities/v1/abilities/test/math/add/run' ); + $request->set_header( 'Content-Type', 'application/json' ); + $request->set_body( + wp_json_encode( + array( + 'input' => array( + 'a' => 10, + 'b' => 7, + ), + ) + ) + ); + + $response = $this->server->dispatch( $request ); + + $this->assertEquals( 200, $response->get_status() ); + $this->assertEquals( 17, $response->get_data() ); + } + /** * Test executing a read-only ability with GET. * From f0d1fc0e4ca85b5fef055f5b047f4cc1760e457c Mon Sep 17 00:00:00 2001 From: Jorge Costa Date: Tue, 3 Feb 2026 16:47:19 +0000 Subject: [PATCH 2/3] feedback application --- src/wp-includes/abilities-api.php | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/src/wp-includes/abilities-api.php b/src/wp-includes/abilities-api.php index ea070892fc785..8d67541843b1f 100644 --- a/src/wp-includes/abilities-api.php +++ b/src/wp-includes/abilities-api.php @@ -226,10 +226,8 @@ * @see wp_register_ability_category() * @see wp_unregister_ability() * - * @param string $name The name of the ability. Must contain 2 to 4 segments separated - * by forward slashes, e.g., `my-plugin/my-ability` or - * `my-plugin/resource/my-ability`. Can only contain lowercase - * alphanumeric characters, dashes, and forward slashes. + * @param string $name The name of the ability. Must be the fully-namespaced + * string identifier, e.g. `my-plugin/my-ability` or `my-plugin/resource/my-ability` * @param array $args { * An associative array of arguments for configuring the ability. * From 4d28ecf4d3862ccb02da4c47e75be68c89ad463d Mon Sep 17 00:00:00 2001 From: Jorge Costa Date: Tue, 3 Feb 2026 16:51:33 +0000 Subject: [PATCH 3/3] comment fixes --- src/wp-includes/abilities-api.php | 2 +- .../abilities-api/class-wp-abilities-registry.php | 6 ++---- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/src/wp-includes/abilities-api.php b/src/wp-includes/abilities-api.php index 8d67541843b1f..835bd535d2487 100644 --- a/src/wp-includes/abilities-api.php +++ b/src/wp-includes/abilities-api.php @@ -227,7 +227,7 @@ * @see wp_unregister_ability() * * @param string $name The name of the ability. Must be the fully-namespaced - * string identifier, e.g. `my-plugin/my-ability` or `my-plugin/resource/my-ability` + * string identifier, e.g. `my-plugin/my-ability` or `my-plugin/resource/my-ability`. * @param array $args { * An associative array of arguments for configuring the ability. * diff --git a/src/wp-includes/abilities-api/class-wp-abilities-registry.php b/src/wp-includes/abilities-api/class-wp-abilities-registry.php index 297712d5f8dce..758dd2c2524df 100644 --- a/src/wp-includes/abilities-api/class-wp-abilities-registry.php +++ b/src/wp-includes/abilities-api/class-wp-abilities-registry.php @@ -43,10 +43,8 @@ final class WP_Abilities_Registry { * * @see wp_register_ability() * - * @param string $name The name of the ability. The name must contain 2 to 4 segments - * separated by forward slashes, e.g. `my-plugin/my-ability` or - * `my-plugin/resource/my-ability`. It can only contain lowercase - * alphanumeric characters, dashes, and forward slashes. + * @param string $name The name of the ability. Must be the fully-namespaced + * string identifier, e.g. `my-plugin/my-ability` or `my-plugin/resource/my-ability`. * @param array $args { * An associative array of arguments for the ability. *