Merge branch 'trunk' into update/docs-annotation

Author: gziolo

docs/1.intro.md

@@ -12,7 +12,7 @@ It acts as a central registry, making it easier for different parts of WordPress
 - **Registry:** A central, singleton object (`WP_Abilities_Registry`) that holds all registered abilities. It provides methods for registering, unregistering, finding, and querying abilities.
 - **Callback:** The PHP function or method executed when an ability is called via `WP_Ability::execute()`.
 - **Schema:** JSON Schema definitions for an ability's expected input (`input_schema`) and its returned output (`output_schema`). This allows for validation and helps agents understand how to use the ability.
-- **Permission Callback:** An optional function that determines if the current user can execute a specific ability. 
+- **Permission Callback:** An optional function that determines if the current user can execute a specific ability.
 - **Namespace:** The first part of an ability name (before the slash), typically matching the plugin or component name that registers the ability.
 
 ## Goals and Benefits
@@ -76,7 +76,8 @@ function my_plugin_register_ability(){
 		'execute_callback' => 'my_plugin_get_siteinfo',
 		'permission_callback' => function( $input ) {
 			return current_user_can( 'manage_options' );
-		}
+		},
+    'show_in_rest' => true,
 	));
 }
 ```

docs/2.getting-started.md

@@ -124,6 +124,7 @@ function my_plugin_register_abilities() {
         'meta'                => array(
             'category' => 'site-info',
         ),
+        'show_in_rest'        => true, // Optional: expose via REST API
     ) );
 }
 

docs/3.registering-abilities.md

@@ -32,6 +32,9 @@ The `$args` array accepts the following keys:
   - `readonly` (`bool`): Whether the ability only reads data without modifying its environment (default: `false`).
   - `destructive` (`bool`): Whether the ability may perform destructive updates to its environment. If `true`, the ability may perform any type of modification, including deletions or other destructive changes. If `false`, the ability performs only additive updates (default: `true`).
   - `idempotent` (`bool`): Whether calling the ability repeatedly with the same arguments will have no additional effect on its environment (default: `false`).
+- `show_in_rest` (`boolean`, **Optional**): Whether to expose this ability via the REST API. Default: `false`.
+  - When `true`, the ability will be listed in REST API responses and can be executed via REST endpoints.
+  - When `false`, the ability will be hidden from REST API listings and cannot be executed via REST endpoints, but remains available for internal PHP usage.
 - `meta` (`array`, **Optional**): An associative array for storing arbitrary additional metadata about the ability.
 
 ## Ability ID Convention

docs/5.rest-api.md

@@ -6,6 +6,15 @@ The WordPress Abilities API provides REST endpoints that allow external systems
 
 Access to all Abilities REST API endpoints requires an authenticated user (see the [Authentication](#authentication) section). Access to execute individual Abilities is restricted based on the `permission_callback()` of the Ability.
 
+## Controlling REST API Exposure
+
+By default, registered abilities are **not** exposed via the REST API. You can control whether an individual ability appears in the REST API by using the `show_in_rest` argument when registering the ability:
+
+- `show_in_rest => true`: The ability is listed in REST API responses and can be executed via REST endpoints.
+- `show_in_rest => false` (default): The ability is hidden from REST API listings and cannot be executed via REST endpoints. The ability remains available for internal PHP usage via `wp_execute_ability()`.
+
+Abilities with `show_in_rest => false` will return a `rest_ability_not_found` error if accessed via REST endpoints.
+
 ## Schema
 
 The Abilities API endpoints are available under the `/wp/v2/abilities` namespace.

includes/abilities-api.php

@@ -25,7 +25,7 @@
  *                                  alphanumeric characters, dashes and the forward slash.
  * @param array<string,mixed> $args An associative array of arguments for the ability. This should include
  *                                  `label`, `description`, `input_schema`, `output_schema`, `execute_callback`,
- *                                  `permission_callback`, `annotations`, `meta`, and `ability_class`.
+ *                                  `permission_callback`, `annotations`, `meta`, `show_in_rest`, and `ability_class`.
  * @return ?\WP_Ability An instance of registered ability on success, null on failure.
  *
  * @phpstan-param array{
@@ -37,6 +37,7 @@
  *   output_schema?: array<string,mixed>,
  *   annotations?: array<string,mixed>,
  *   meta?: array<string,mixed>,
+ *   show_in_rest?: bool,
  *   ability_class?: class-string<\WP_Ability>,
  *   ...<string, mixed>
  * } $args

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

@@ -59,6 +59,7 @@ final class WP_Abilities_Registry {
 	 *   output_schema?: array<string,mixed>,
 	 *   annotations?: array<string,mixed>,
 	 *   meta?: array<string,mixed>,
+	 *   show_in_rest?: bool,
 	 *   ability_class?: class-string<\WP_Ability>,
 	 *   ...<string, mixed>
 	 * } $args

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

@@ -116,6 +116,14 @@ class WP_Ability {
 	 */
 	protected $meta = array();
 
+	/**
+	 * Whether to show the ability in the REST API.
+	 *
+	 * @since n.e.x.t
+	 * @var bool
+	 */
+	protected $show_in_rest = false;
+
 	/**
 	 * Constructor.
 	 *
@@ -128,9 +136,9 @@ class WP_Ability {
 	 * @see wp_register_ability()
 	 *
 	 * @param string              $name The name of the ability, with its namespace.
-	 * @param array<string,mixed> $args An associative array of arguments for the ability. This should
-	 *                                  include `label`, `description`, `input_schema`, `output_schema`,
-	 *                                  `execute_callback`, `permission_callback`, `annotations`, and `meta`.
+	 * @param array<string,mixed> $args An associative array of arguments for the ability. This should include
+	 *                                  `label`, `description`, `input_schema`, `output_schema`, `execute_callback`,
+	 *                                  `permission_callback`, `annotations`, `meta`, and `show_in_rest`.
 	 */
 	public function __construct( string $name, array $args ) {
 		$this->name = $name;
@@ -180,6 +188,7 @@ public function __construct( string $name, array $args ) {
 	 *   output_schema?: array<string,mixed>,
 	 *   annotations?: array<string,mixed>,
 	 *   meta?: array<string,mixed>,
+	 *   show_in_rest?: bool,
 	 *   ...<string, mixed>,
 	 * } $args
 	 */
@@ -234,6 +243,12 @@ protected function prepare_properties( array $args ): array {
 			);
 		}
 
+		if ( isset( $args['show_in_rest'] ) && ! is_bool( $args['show_in_rest'] ) ) {
+			throw new \InvalidArgumentException(
+				esc_html__( 'The ability properties should provide a valid `show_in_rest` boolean.' )
+			);
+		}
+
 		// Set defaults for optional args.
 		$args['annotations'] = wp_parse_args(
 			$args['annotations'] ?? array(),
@@ -321,6 +336,17 @@ public function get_meta(): array {
 		return $this->meta;
 	}
 
+	/**
+	 * Checks whether the ability should be shown in the REST API.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @return bool True if the ability should be shown in the REST API, false otherwise.
+	 */
+	public function show_in_rest(): bool {
+		return $this->show_in_rest;
+	}
+
 	/**
 	 * Validates input data against the input schema.
 	 *

includes/rest-api/endpoints/class-wp-rest-abilities-list-controller.php

@@ -94,7 +94,12 @@ public function register_routes(): void {
 	 * @return \WP_REST_Response Response object on success.
 	 */
 	public function get_items( $request ) {
-		$abilities = wp_get_abilities();
+		$abilities = array_filter(
+			wp_get_abilities(),
+			static function ( $ability ) {
+				return $ability->show_in_rest();
+			}
+		);
 
 		// Handle pagination with explicit defaults.
 		$params   = $request->get_params();
@@ -150,8 +155,7 @@ public function get_items( $request ) {
 	 */
 	public function get_item( $request ) {
 		$ability = wp_get_ability( $request->get_param( 'name' ) );
-
-		if ( ! $ability ) {
+		if ( ! $ability || ! $ability->show_in_rest() ) {
 			return new \WP_Error(
 				'rest_ability_not_found',
 				__( 'Ability not found.' ),

includes/rest-api/endpoints/class-wp-rest-abilities-run-controller.php

@@ -154,7 +154,7 @@ public function run_ability( $request ) {
 	 */
 	public function run_ability_permissions_check( $request ) {
 		$ability = wp_get_ability( $request->get_param( 'name' ) );
-		if ( ! $ability ) {
+		if ( ! $ability || ! $ability->show_in_rest() ) {
 			return new \WP_Error(
 				'rest_ability_not_found',
 				__( 'Ability not found.' ),

tests/unit/abilities-api/wpAbilitiesRegistry.php

@@ -62,6 +62,7 @@ public function set_up(): void {
 			'meta'                => array(
 				'category' => 'math',
 			),
+			'show_in_rest'        => true,
 		);
 	}
 
@@ -297,6 +298,21 @@ public function test_register_invalid_meta_type() {
 		$this->assertNull( $result );
 	}
 
+	/**
+	 * Should reject ability registration with invalid show in REST type.
+	 *
+	 * @covers WP_Abilities_Registry::register
+	 * @covers WP_Ability::prepare_properties
+	 *
+	 * @expectedIncorrectUsage WP_Abilities_Registry::register
+	 */
+	public function test_register_invalid_show_in_rest_type() {
+		self::$test_ability_args['show_in_rest'] = 5;
+
+		$result = $this->registry->register( self::$test_ability_name, self::$test_ability_args );
+		$this->assertNull( $result );
+	}
+
 	/**
 	 * Should reject registration for already registered ability.
 	 *