WordPress.org
Get WordPress

Make WordPress Core

Changeset 61602


Ignore:
Timestamp:
02/09/2026 04:59:52 PM (4 weeks ago)
Author:
jorgefilipecosta
Message:

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.
This allows plugins to organize abilities into logical resource groups. The validation regex changes from /^[a-z0-9-]+\/[a-z0-9-]+$/ to /^[a-z0-9-]+(?:\/[a-z0-9-]+){1,3}$/, which accepts the first segment plus 1-3 additional slash-delimited segments.
Updates the validation regex, error messages, docblocks, and adds corresponding unit and REST API tests.

Props jorgefilipecosta, justlevine, jorbin.
Fixes #64596.

Location:
trunk
Files:
5 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/abilities-api.php

    r61130 r61602  
    133133 * Ability names must follow these rules:
    134134 *
    135  *  - Include a namespace prefix (e.g., `my-plugin/my-ability`).
     135 *  - Contain 2 to 4 segments separated by forward slashes
     136 *    (e.g., `my-plugin/my-ability`, `my-plugin/resource/find`, `my-plugin/resource/sub/find`).
    136137 *  - Use only lowercase alphanumeric characters, dashes, and forward slashes.
    137138 *  - Use descriptive, action-oriented names (e.g., `process-payment`, `generate-report`).
    … …  
    226227 * @see wp_unregister_ability()
    227228 *
    228  * @param string               $name The name of the ability. Must be a namespaced string containing
    229  *                                   a prefix, e.g., `my-plugin/my-ability`. Can only contain lowercase
    230  *                                   alphanumeric characters, dashes, and forward slashes.
     229 * @param string               $name The name of the ability. Must be the fully-namespaced
     230 *                                   string identifier, e.g. `my-plugin/my-ability` or `my-plugin/resource/my-ability`.
    231231 * @param array<string, mixed> $args {
    232232 *     An associative array of arguments for configuring the ability.
    … …  
    319319 *
    320320 * @param string $name The name of the ability to unregister, including namespace prefix
    321  *                     (e.g., 'my-plugin/my-ability').
     321 *                     (e.g., 'my-plugin/my-ability' or 'my-plugin/resource/find').
    322322 * @return WP_Ability|null The unregistered ability instance on success, `null` on failure.
    323323 */
    … …  
    352352 *
    353353 * @param string $name The name of the ability to check, including namespace prefix
    354  *                     (e.g., 'my-plugin/my-ability').
     354 *                     (e.g., 'my-plugin/my-ability' or 'my-plugin/resource/find').
    355355 * @return bool `true` if the ability is registered, `false` otherwise.
    356356 */
    … …  
    384384 *
    385385 * @param string $name The name of the ability, including namespace prefix
    386  *                     (e.g., 'my-plugin/my-ability').
     386 *                     (e.g., 'my-plugin/my-ability' or 'my-plugin/resource/find').
    387387 * @return WP_Ability|null The registered ability instance, or `null` if not registered.
    388388 */

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

    r61086 r61602  
    4444     * @see wp_register_ability()
    4545     *
    46      * @param string               $name The name of the ability. The name must be a string containing a namespace
    47      *                                   prefix, i.e. `my-plugin/my-ability`. It can only contain lowercase
    48      *                                   alphanumeric characters, dashes and the forward slash.
     46     * @param string               $name The name of the ability. Must be the fully-namespaced
     47 *                                       string identifier, e.g. `my-plugin/my-ability` or `my-plugin/resource/my-ability`.
    4948     * @param array<string, mixed> $args {
    5049     *     An associative array of arguments for the ability.
    … …  
    7978     */
    8079    public function register( string $name, array $args ): ?WP_Ability {
    81         if ( ! preg_match( '/^[a-z0-9-]+\/[a-z0-9-]+$/', $name ) ) {
     80        if ( ! preg_match( '/^[a-z0-9-]+(?:\/[a-z0-9-]+){1,3}$/', $name ) ) {
    8281            _doing_it_wrong(
    8382                __METHOD__,
    8483                __(
    85                     '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.'
     84                    '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.'
    8685                ),
    8786                '6.9.0'

  • trunk/src/wp-includes/abilities-api/class-wp-ability.php

    r61505 r61602  
    5353    /**
    5454     * The name of the ability, with its namespace.
    55      * Example: `my-plugin/my-ability`.
     55     * Examples: `my-plugin/my-ability`, `my-plugin/resource/find`.
    5656     *
    5757     * @since 6.9.0
    … …  
    341341    /**
    342342     * Retrieves the name of the ability, with its namespace.
    343      * Example: `my-plugin/my-ability`.
     343     * Examples: `my-plugin/my-ability`, `my-plugin/resource/find`.
    344344     *
    345345     * @since 6.9.0

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

    r61390 r61602  
    138138
    139139    /**
     140     * Should accept ability name with 3 segments (2 slashes).
     141     *
     142     * @ticket 64098
     143     *
     144     * @covers WP_Abilities_Registry::register
     145     */
     146    public function test_register_valid_name_with_three_segments() {
     147        $result = $this->registry->register( 'test/sub/add-numbers', self::$test_ability_args );
     148        $this->assertInstanceOf( WP_Ability::class, $result );
     149        $this->assertSame( 'test/sub/add-numbers', $result->get_name() );
     150    }
     151
     152    /**
     153     * Should accept ability name with 4 segments (3 slashes).
     154     *
     155     * @ticket 64098
     156     *
     157     * @covers WP_Abilities_Registry::register
     158     */
     159    public function test_register_valid_name_with_four_segments() {
     160        $result = $this->registry->register( 'test/sub/deep/add-numbers', self::$test_ability_args );
     161        $this->assertInstanceOf( WP_Ability::class, $result );
     162        $this->assertSame( 'test/sub/deep/add-numbers', $result->get_name() );
     163    }
     164
     165    /**
     166     * Should reject ability name with 5 segments (exceeds maximum of 4).
     167     *
     168     * @ticket 64098
     169     *
     170     * @covers WP_Abilities_Registry::register
     171     *
     172     * @expectedIncorrectUsage WP_Abilities_Registry::register
     173     */
     174    public function test_register_invalid_name_with_five_segments() {
     175        $result = $this->registry->register( 'test/a/b/c/too-deep', self::$test_ability_args );
     176        $this->assertNull( $result );
     177    }
     178
     179    /**
     180     * Should reject ability name with empty segments (double slashes).
     181     *
     182     * @ticket 64098
     183     *
     184     * @covers WP_Abilities_Registry::register
     185     *
     186     * @expectedIncorrectUsage WP_Abilities_Registry::register
     187     */
     188    public function test_register_invalid_name_with_empty_segment() {
     189        $result = $this->registry->register( 'test//add-numbers', self::$test_ability_args );
     190        $this->assertNull( $result );
     191    }
     192
     193    /**
     194     * Should reject ability name with trailing slash.
     195     *
     196     * @ticket 64098
     197     *
     198     * @covers WP_Abilities_Registry::register
     199     *
     200     * @expectedIncorrectUsage WP_Abilities_Registry::register
     201     */
     202    public function test_register_invalid_name_with_trailing_slash() {
     203        $result = $this->registry->register( 'test/add-numbers/', self::$test_ability_args );
     204        $this->assertNull( $result );
     205    }
     206
     207    /**
    140208     * Should reject ability registration without a label.
    141209     *

  • trunk/tests/phpunit/tests/rest-api/wpRestAbilitiesV1RunController.php

    r61373 r61602  
    380380        );
    381381
     382        // Ability with nested namespace (3 segments).
     383        $this->register_test_ability(
     384            'test/math/add',
     385            array(
     386                'label'               => 'Nested Add',
     387                'description'         => 'Adds numbers with nested namespace',
     388                'category'            => 'math',
     389                'input_schema'        => array(
     390                    'type'                 => 'object',
     391                    'properties'           => array(
     392                        'a' => array(
     393                            'type'        => 'number',
     394                            'description' => 'First number',
     395                        ),
     396                        'b' => array(
     397                            'type'        => 'number',
     398                            'description' => 'Second number',
     399                        ),
     400                    ),
     401                    'required'             => array( 'a', 'b' ),
     402                    'additionalProperties' => false,
     403                ),
     404                'output_schema'       => array(
     405                    'type' => 'number',
     406                ),
     407                'execute_callback'    => static function ( array $input ) {
     408                    return $input['a'] + $input['b'];
     409                },
     410                'permission_callback' => static function () {
     411                    return current_user_can( 'edit_posts' );
     412                },
     413                'meta'                => array(
     414                    'show_in_rest' => true,
     415                ),
     416            )
     417        );
     418
    382419        // Read-only ability for query params testing.
    383420        $this->register_test_ability(
    … …  
    431468        $this->assertEquals( 200, $response->get_status() );
    432469        $this->assertEquals( 8, $response->get_data() );
     470    }
     471
     472    /**
     473     * Test executing an ability with a nested namespace (3 segments) via REST.
     474     *
     475     * @ticket 64098
     476     */
     477    public function test_execute_nested_namespace_ability(): void {
     478        $request = new WP_REST_Request( 'POST', '/wp-abilities/v1/abilities/test/math/add/run' );
     479        $request->set_header( 'Content-Type', 'application/json' );
     480        $request->set_body(
     481            wp_json_encode(
     482                array(
     483                    'input' => array(
     484                        'a' => 10,
     485                        'b' => 7,
     486                    ),
     487                )
     488            )
     489        );
     490
     491        $response = $this->server->dispatch( $request );
     492
     493        $this->assertEquals( 200, $response->get_status() );
     494        $this->assertEquals( 17, $response->get_data() );
    433495    }
    434496
Note: See TracChangeset for help on using the changeset viewer.