dev: add wp_ability_args filter [Proposal]

docs/5.hooks.md

@@ -0,0 +1,75 @@
+# Using Action and Filter Hooks
+
+The Abilities API provides action and filter hooks that allow developers to customize and extend its functionality. Below are the available hooks:
+
+## Quick Links
+
+- [Actions](#actions)
+- [Filters](#filters)
+  - [`wp_ability_args`](#wp_ability_args)
+
+## Actions
+
+There are currently **no Action hooks** provided by this version of the Abilities API.
+
+## Filters
+
+### `wp_ability_args`
+
+> [!IMPORTANT]
+> This filter is prefixed with `wp_` to avoid potential naming collisions.
+> Once merged into WordPress core, the prefix will likely be removed to preserve backward-compatibility.
+
+Allows modification of an Ability's args before they are validated and used to instantiate the Ability.
+
+```php
+apply_filters( 'wp_ability_args', array $args, string $ability_name );
+```
+
+#### Parameters
+
+- `$args` (`array<string,mixed>`): The arguments used to instantiate the ability. See [wp_register_ability()](./3.registering-abilities.md#wp_register_ability) for the full list of args.
+- `$ability_name` (`string`): The name of the ability, with its namespace.
+
+#### Example
+
+```php
+/**
+ * Modify ability args before validation.
+ * @param array<string,mixed> $args The arguments used to instantiate the ability.
+ * @param string        $ability_name The name of the ability, with its namespace.
+ * @return array<string,mixed> The modified ability arguments.
+ */
+function my_modify_ability_args( array $args, string $ability_name ): array {
+  // Check if the ability name matches what you're looking for.
+  if ( 'my-namespace/my-ability' !== $ability_name ) {
+    return $args;
+  }
+
+  // Modify the args as needed.
+  $args['label'] = __('My Custom Ability Label');
+
+  // You can use the old args to build new ones.
+  $args['description'] = sprintf(
+    /* translators: 1: Ability name 2: Previous description */
+    __('This is a custom description for the ability %s. Previously the description was %s', 'text-domain'),
+    $ability_name,
+    $args['description'] ?? 'N/A'
+  );
+
+  // Even if they're callbacks.
+  $args['has_permissions' ] = static function ( $input = null ) use ( $args, $ability_name ) {
+    $previous_check = is_callable( $args['has_permissions'] ) ? $args['has_permissions']( $input ) : true;
+
+    // If we already failed, no need for stricter checks.
+    if ( ! $previous_check || is_wp_error( $previous_check ) ) {
+      return $previous_check;
+    }
+
+    return current_user_can( 'my_custom_ability_cap', $ability_name );
+  }
+
+  return $args;
+}
+add_filter( 'wp_ability_args', 'my_modify_ability_args', 10, 2 );
+```

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

@@ -64,6 +64,16 @@ final class WP_Abilities_Registry {
 	 * } $args
 	 */
 	public function register( string $name, array $args ): ?WP_Ability {
+		/**
+		 * Filters the ability arguments before they are validated.
+		 *
+		 * @since n.e.x.t
+		 *
+		 * @param array<string,mixed> $args The arguments used to instantiate the ability.
+		 * @param string              $name The name of the ability, with its namespace.
+		 */
+		$args = apply_filters( 'wp_ability_args', $args, $name );
+
 		if ( ! preg_match( '/^[a-z0-9-]+\/[a-z0-9-]+$/', $name ) ) {
 			_doing_it_wrong(
 				__METHOD__,
@@ -94,6 +104,8 @@ public function register( string $name, array $args ): ?WP_Ability {
 			);
 			return null;
 		}
+
+		/** @var class-string<\WP_Ability> */
 		$ability_class = $args['ability_class'] ?? WP_Ability::class;
 		unset( $args['ability_class'] );