Changeset 61602 for trunk/src/wp-includes/abilities-api.php

Timestamp:

02/09/2026 04:59:52 PM (2 months 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.

File:

• trunk/src/wp-includes/abilities-api.php (modified) (5 diffs)

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

@@ -133 +133 @@
  * 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`).
@@ -226 +227 @@
  * @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
- *                                   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<string, mixed> $args {
  *     An associative array of arguments for configuring the ability.
@@ -319 +319 @@
  *
  * @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.
  */
@@ -352 +352 @@
  *
  * @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.
  */
@@ -384 +384 @@
  *
  * @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.
  */