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

Timestamp:

08/24/2026 07:42:56 AM (4 weeks ago)

Author:

gziolo

Message:

Make the ability category optional

When the category argument is omitted during ability registration, the registry now assigns the built-in uncategorized category. This category is registered alongside the other core ability categories.

Previously, the registry only validated a category when one was provided, but WP_Ability still required the argument, so a registration without a category could never succeed. The fallback is applied before validation, so invalid values are still rejected. This includes non-string types and empty or unregistered category slugs.

Also updates the public API documentation and adds regression coverage for the fallback and for invalid category values.

Props hokansardar, sachinrajcp123, jorgefilipecosta, gziolo.
Fixes #65569.

File:

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

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

@@ -129 +129 @@
  *     add_action( 'wp_abilities_api_init', 'my_plugin_register_abilities' );
  *
+ * On failure, this function returns `null` and calls `_doing_it_wrong()` with the reason.
+ * By default, the resulting notice is displayed when `WP_DEBUG` is enabled.
+ *
  * ### Naming Conventions
  *
@@ -139 +142 @@
  * ### Categories
  *
- * Abilities must be organized into categories. Ability categories provide better
- * discoverability and must be registered before the abilities that reference them:
+ * Abilities can be organized into categories. If no category is provided, the ability is
+ * assigned to the built-in `uncategorized` category. Custom categories must be registered
+ * before the abilities that reference them:
  *
  *     function my_plugin_register_categories(): void {
@@ -229 +233 @@
  *
  * @since 6.9.0
+ * @since 7.2.0 The `category` argument is now optional and defaults to `uncategorized`.
  *
  * @see WP_Abilities_Registry::register()
@@ -243 +248 @@
  *     @type string               $description         Required. A detailed description of what the ability does
  *                                                     and when it should be used.
- *     @type string               $category            Required. The ability category slug this ability belongs to.
- *                                                     The ability category must be registered via `wp_register_ability_category()`
- *                                                     before registering the ability.
+ *     @type string               $category            Optional. The ability category slug this ability belongs to.
+ *                                                     Defaults to `uncategorized`. Custom categories must be registered
+ *                                                     via `wp_register_ability_category()` before registering the ability.
  *     @type callable             $execute_callback    Required. A callback function to execute when the ability is invoked.
  *                                                     Receives optional mixed input data and must return either a result
@@ -608 +613 @@
  *
  * Ability categories provide a way to organize and group related abilities for better
- * discoverability and management. Ability categories must be registered before abilities
- * that reference them.
+ * discoverability and management. Custom categories must be registered before abilities
+ * that reference them. Abilities that omit a category are assigned to the built-in
+ * `uncategorized` category, which is intended as an escape hatch for simple or transitional
+ * registrations.
  *
  * Ability categories must be registered on the `wp_abilities_api_categories_init` action hook.
@@ -625 +632 @@
  *     }
  *     add_action( 'wp_abilities_api_categories_init', 'my_plugin_register_categories' );
+ *
+ * On failure, this function returns `null` and calls `_doing_it_wrong()` with the reason.
+ * By default, the resulting notice is displayed when `WP_DEBUG` is enabled.
  *
  * @since 6.9.0