Improve support for annotations, including DELETE handling in REST API

gziolo · gziolo · commit 39396dce1baf · 2025-10-18T16:48:55.000+02:00
diff --git a/src/wp-includes/abilities-api.php b/src/wp-includes/abilities-api.php
@@ -38,8 +38,8 @@
  *     @type array<string, mixed> $meta                  {
  *         Optional. Additional metadata for the ability.
  *
- *         @type array<string, bool|string> $annotations  Optional. Annotation metadata for the ability.
- *         @type bool                       $show_in_rest Optional. Whether to expose this ability in the REST API. Default false.
+ *         @type array<string, null|bool> $annotations  Optional. Annotation metadata for the ability.
+ *         @type bool                     $show_in_rest Optional. Whether to expose this ability in the REST API. Default false.
  *     }
  *     @type string               $ability_class       Optional. Custom class to instantiate instead of WP_Ability.
  * }
diff --git a/src/wp-includes/abilities-api/class-wp-abilities-registry.php b/src/wp-includes/abilities-api/class-wp-abilities-registry.php
@@ -61,8 +61,8 @@ final class WP_Abilities_Registry {
 	 *     @type array<string, mixed> $meta                  {
 	 *         Optional. Additional metadata for the ability.
 	 *
-	 *         @type array<string, bool|string> $annotations  Optional. Annotation metadata for the ability.
-	 *         @type bool                       $show_in_rest Optional. Whether to expose this ability in the REST API. Default false.
+	 *         @type array<string, null|bool> $annotations  Optional. Annotation metadata for the ability.
+	 *         @type bool                     $show_in_rest Optional. Whether to expose this ability in the REST API. Default false.
 	 *     }
 	 *     @type string               $ability_class         Optional. Custom class to instantiate instead of WP_Ability.
 	 * }
diff --git a/src/wp-includes/abilities-api/class-wp-ability.php b/src/wp-includes/abilities-api/class-wp-ability.php
@@ -33,21 +33,21 @@ class WP_Ability {
 	 * They are not guaranteed to provide a faithful description of ability behavior.
 	 *
 	 * @since 6.9.0
-	 * @var array<string, (bool|string)>
+	 * @var array<string, (null|bool)>
 	 */
 	protected static $default_annotations = array(
 		// If true, the ability does not modify its environment.
-		'readonly'    => false,
+		'readonly'    => null,
 		/*
 		 * If true, the ability may perform destructive updates to its environment.
 		 * If false, the ability performs only additive updates.
 		 */
-		'destructive' => false,
+		'destructive' => null,
 		/*
 		 * If true, calling the ability repeatedly with the same arguments will have no additional effect
 		 * on its environment.
 		 */
-		'idempotent'  => false,
+		'idempotent'  => null,
 	);
 
 	/**
@@ -150,8 +150,8 @@ class WP_Ability {
 	 *     @type array<string, mixed> $meta                  {
 	 *         Optional. Additional metadata for the ability.
 	 *
-	 *         @type array<string, bool|string> $annotations  Optional. Annotation metadata for the ability.
-	 *         @type bool                       $show_in_rest Optional. Whether to expose this ability in the REST API. Default false.
+	 *         @type array<string, null|bool> $annotations  Optional. Annotation metadata for the ability.
+	 *         @type bool                     $show_in_rest Optional. Whether to expose this ability in the REST API. Default false.
 	 *     }
 	 * }
 	 */
@@ -205,8 +205,8 @@ public function __construct( string $name, array $args ) {
 	 *     @type array<string, mixed> $meta                  {
 	 *         Optional. Additional metadata for the ability.
 	 *
-	 *         @type array<string, bool|string> $annotations  Optional. Annotation metadata for the ability.
-	 *         @type bool                       $show_in_rest Optional. Whether to expose this ability in the REST API. Default false.
+	 *         @type array<string, null|bool> $annotations  Optional. Annotation metadata for the ability.
+	 *         @type bool                     $show_in_rest Optional. Whether to expose this ability in the REST API. Default false.
 	 *     }
 	 * }
 	 * @return array<string, mixed> {
@@ -224,8 +224,8 @@ public function __construct( string $name, array $args ) {
 	 *     @type array<string, mixed> $meta                  {
 	 *         Additional metadata for the ability.
 	 *
-	 *         @type array<string, bool|string> $annotations  Optional. Annotation metadata for the ability.
-	 *         @type bool                       $show_in_rest Whether to expose this ability in the REST API. Default false.
+	 *         @type array<string, null|bool> $annotations  Optional. Annotation metadata for the ability.
+	 *         @type bool                     $show_in_rest Whether to expose this ability in the REST API. Default false.
 	 *     }
 	 * }
 	 * @throws InvalidArgumentException if an argument is invalid.
diff --git a/src/wp-includes/rest-api/endpoints/class-wp-rest-abilities-run-controller.php b/src/wp-includes/rest-api/endpoints/class-wp-rest-abilities-run-controller.php
@@ -91,22 +91,24 @@ public function run_ability_with_method_check( $request ) {
 		}
 
 		// Check if the HTTP method matches the ability annotations.
-		$annotations = $ability->get_meta_item( 'annotations' );
-		$is_readonly = ! empty( $annotations['readonly'] );
-		$method      = $request->get_method();
-
-		if ( $is_readonly && 'GET' !== $method ) {
-			return new WP_Error(
-				'rest_ability_invalid_method',
-				__( 'Read-only abilities require GET method.' ),
-				array( 'status' => 405 )
-			);
+		$annotations     = $ability->get_meta_item( 'annotations' );
+		$expected_method = 'POST';
+		if ( ! empty( $annotations['readonly'] ) ) {
+			$expected_method = 'GET';
+		} elseif ( ! empty( $annotations['destructive'] ) && ! empty( $annotations['idempotent'] ) ) {
+			$expected_method = 'DELETE';
 		}
 
-		if ( ! $is_readonly && 'POST' !== $method ) {
+		if ( $expected_method !== $request->get_method() ) {
+			$error_message = __( 'Abilities that perform updates require POST method.' );
+			if ( 'GET' === $expected_method ) {
+				$error_message = __( 'Read-only abilities require GET method.' );
+			} elseif ( 'DELETE' === $expected_method ) {
+				$error_message = __( 'Abilities that perform destructive actions require DELETE method.' );
+			}
 			return new WP_Error(
 				'rest_ability_invalid_method',
-				__( 'Abilities that perform updates require POST method.' ),
+				$error_message,
 				array( 'status' => 405 )
 			);
 		}
@@ -183,8 +185,8 @@ public function run_ability_permissions_check( $request ) {
 	 * @return mixed|null The input parameters.
 	 */
 	private function get_input_from_request( $request ) {
-		if ( 'GET' === $request->get_method() ) {
-			// For GET requests, look for 'input' query parameter.
+		if ( in_array( $request->get_method(), array( 'GET', 'DELETE' ) ) ) {
+			// For GET and DELETE requests, look for 'input' query parameter.
 			$query_params = $request->get_query_params();
 			return $query_params['input'] ?? null;
 		}
@@ -226,7 +228,7 @@ public function get_run_schema(): array {
 			'properties' => array(
 				'result' => array(
 					'description' => __( 'The result of the ability execution.' ),
-					'context'     => array( 'view' ),
+					'context'     => array( 'view', 'edit' ),
 					'readonly'    => true,
 				),
 			),
diff --git a/tests/phpunit/tests/abilities-api/wpAbility.php b/tests/phpunit/tests/abilities-api/wpAbility.php
@@ -111,11 +111,11 @@ public function test_meta_get_non_existing_item_with_custom_default() {
 	public function test_get_merged_annotations_from_meta() {
 		$ability = new WP_Ability( self::$test_ability_name, self::$test_ability_properties );
 
-		$this->assertEquals(
+		$this->assertSame(
 			array_merge(
 				self::$test_ability_properties['meta']['annotations'],
 				array(
-					'idempotent' => false,
+					'idempotent' => null,
 				)
 			),
 			$ability->get_meta_item( 'annotations' )
@@ -135,9 +135,9 @@ public function test_get_default_annotations_from_meta() {
 
 		$this->assertSame(
 			array(
-				'readonly'    => false,
-				'destructive' => false,
-				'idempotent'  => false,
+				'readonly'    => null,
+				'destructive' => null,
+				'idempotent'  => null,
 			),
 			$ability->get_meta_item( 'annotations' )
 		);
diff --git a/tests/phpunit/tests/rest-api/wpRestAbilitiesRunController.php b/tests/phpunit/tests/rest-api/wpRestAbilitiesRunController.php
@@ -228,6 +228,47 @@ private function register_test_abilities(): void {
 			)
 		);
 
+		// Destructive ability (DELETE method).
+		wp_register_ability(
+			'test/delete-user',
+			array(
+				'label'               => 'Delete User',
+				'description'         => 'Deletes a user',
+				'category'            => 'system',
+				'input_schema'        => array(
+					'type'       => 'object',
+					'properties' => array(
+						'user_id' => array(
+							'type'    => 'integer',
+							'default' => 0,
+						),
+					),
+				),
+				'output_schema'       => array(
+					'type'     => 'string',
+					'required' => true,
+				),
+				'execute_callback'    => static function ( array $input ) {
+					$user_id = $input['user_id'] ?? get_current_user_id();
+					$user    = get_user_by( 'id', $user_id );
+					if ( ! $user ) {
+						return new WP_Error( 'user_not_found', 'User not found' );
+					}
+					return 'User successfully deleted!';
+				},
+				'permission_callback' => static function () {
+					return is_user_logged_in();
+				},
+				'meta'                => array(
+					'annotations'  => array(
+						'destructive' => true,
+						'idempotent'  => true,
+					),
+					'show_in_rest' => true,
+				),
+			)
+		);
+
 		// Ability with contextual permissions
 		wp_register_ability(
 			'test/restricted',
@@ -402,6 +443,27 @@ public function test_execute_readonly_ability_get(): void {
 		$this->assertEquals( self::$user_id, $data['id'] );
 	}
 
+	/**
+	 * Test executing a destructive ability with GET.
+	 *
+	 * @ticket 64098
+	 */
+	public function test_execute_destructive_ability_delete(): void {
+		$request = new WP_REST_Request( 'DELETE', '/wp/v2/abilities/test/delete-user/run' );
+		$request->set_query_params(
+			array(
+				'input' => array(
+					'user_id' => self::$user_id,
+				),
+			)
+		);
+
+		$response = $this->server->dispatch( $request );
+
+		$this->assertEquals( 200, $response->get_status() );
+		$this->assertEquals( 'User successfully deleted!', $response->get_data() );
+	}
+
 	/**
 	 * Test HTTP method validation for regular abilities.
 	 *
@@ -452,6 +514,24 @@ public function test_readonly_ability_requires_get(): void {
 		$this->assertSame( 'Read-only abilities require GET method.', $data['message'] );
 	}
 
+	/**
+	 * Test HTTP method validation for destructive abilities.
+	 *
+	 * @ticket 64098
+	 */
+	public function test_destructive_ability_requires_delete(): void {
+		// Try POST on a destructive ability (should fail).
+		$request = new WP_REST_Request( 'POST', '/wp/v2/abilities/test/delete-user/run' );
+		$request->set_header( 'Content-Type', 'application/json' );
+		$request->set_body( wp_json_encode( array( 'user_id' => 1 ) ) );
+
+		$response = $this->server->dispatch( $request );
+
+		$this->assertSame( 405, $response->get_status() );
+		$data = $response->get_data();
+		$this->assertSame( 'rest_ability_invalid_method', $data['code'] );
+		$this->assertSame( 'Abilities that perform destructive actions require DELETE method.', $data['message'] );
+	}
 
 	/**
 	 * Test output validation against schema.
