Abilities: Address review feedback for ability deprecation

- Support `true` as a shorthand for the `deprecated` meta filter in
  `wp_get_abilities()`, so REST API and PHP callers can request only
  deprecated abilities.
- Validate that the deprecation `replacement` detail is a namespaced
  ability name.
- Handle the `deprecated_ability_run` action while serving REST API
  requests. The notice becomes an `X-WP-DeprecatedAbility` header
  instead of corrupting the JSON response when `WP_DEBUG` is enabled.
- Document the `deprecated` collection parameter details in the REST
  API schema.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: gziolo

src/wp-includes/abilities-api.php

@@ -539,9 +539,10 @@ function _deprecated_ability( string $ability_name, string $version = '', string
  *         'meta' => array( 'deprecated' => false ),
  *     ) );
  *
- *     // Return only deprecated abilities.
+ *     // Return only deprecated abilities. Passing `true` matches any deprecated
+ *     // ability. An array of details narrows the results further.
  *     $abilities = wp_get_abilities( array(
- *         'meta' => array( 'deprecated' => array() ),
+ *         'meta' => array( 'deprecated' => true ),
  *     ) );
  *
  *     // Filter by category.
@@ -624,6 +625,15 @@ function wp_get_abilities( array $args = array() ): array {
 	$item_include_callback = isset( $args['item_include_callback'] ) && is_callable( $args['item_include_callback'] ) ? $args['item_include_callback'] : null;
 	$result_callback       = isset( $args['result_callback'] ) && is_callable( $args['result_callback'] ) ? $args['result_callback'] : null;
 
+	/*
+	 * Normalize the `deprecated` meta filter shorthand. Stored values are `false`
+	 * or an array of details, so `true` becomes an empty set of conditions that
+	 * matches any deprecated ability.
+	 */
+	if ( isset( $meta['deprecated'] ) && true === $meta['deprecated'] ) {
+		$meta['deprecated'] = array();
+	}
+
 	$matched = array();
 
 	foreach ( $abilities as $name => $ability ) {

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

@@ -401,6 +401,12 @@ protected function prepare_properties( array $args ): array {
 					);
 				}
 
+				if ( 'replacement' === $key && ! preg_match( '/^[a-z0-9-]+\/[a-z0-9-]+$/', $args['meta']['deprecated'][ $key ] ) ) {
+					throw new InvalidArgumentException(
+						__( 'The ability deprecation `replacement` value should be a namespaced ability name, i.e. "my-plugin/my-ability". It can only contain lowercase alphanumeric characters, dashes and the forward slash.' )
+					);
+				}
+
 				$has_deprecation_details = true;
 			}
 

src/wp-includes/rest-api.php

@@ -244,6 +244,8 @@ function rest_api_default_filters() {
 		add_filter( 'deprecated_function_trigger_error', '__return_false' );
 		add_action( 'deprecated_argument_run', 'rest_handle_deprecated_argument', 10, 3 );
 		add_filter( 'deprecated_argument_trigger_error', '__return_false' );
+		add_action( 'deprecated_ability_run', 'rest_handle_deprecated_ability', 10, 4 );
+		add_filter( 'deprecated_ability_trigger_error', '__return_false' );
 		add_action( 'doing_it_wrong_run', 'rest_handle_doing_it_wrong', 10, 3 );
 		add_filter( 'doing_it_wrong_trigger_error', '__return_false' );
 	}
@@ -767,6 +769,42 @@ function rest_handle_deprecated_argument( $function_name, $message, $version ) {
 	header( sprintf( 'X-WP-DeprecatedParam: %s', $string ) );
 }
 
+/**
+ * Handles _deprecated_ability() errors.
+ *
+ * @since 7.2.0
+ *
+ * @param string $ability_name The ability that was executed.
+ * @param string $replacement  The ability that should be used as a replacement.
+ * @param string $version      The version of the ability provider that deprecated the ability.
+ * @param string $message      Additional migration guidance.
+ */
+function rest_handle_deprecated_ability( $ability_name, $replacement, $version, $message ) {
+	if ( ! WP_DEBUG || headers_sent() ) {
+		return;
+	}
+
+	if ( $version && $replacement ) {
+		/* translators: 1: Ability name, 2: Version number, 3: Alternative ability name. */
+		$string = sprintf( __( '%1$s (since %2$s; use %3$s instead)' ), $ability_name, $version, $replacement );
+	} elseif ( $version ) {
+		/* translators: 1: Ability name, 2: Version number. */
+		$string = sprintf( __( '%1$s (since %2$s; no alternative available)' ), $ability_name, $version );
+	} elseif ( $replacement ) {
+		/* translators: 1: Ability name, 2: Alternative ability name. */
+		$string = sprintf( __( '%1$s (use %2$s instead)' ), $ability_name, $replacement );
+	} else {
+		/* translators: %s: Ability name. */
+		$string = sprintf( __( '%s (no alternative available)' ), $ability_name );
+	}
+
+	if ( $message ) {
+		$string .= ' ' . $message;
+	}
+
+	header( sprintf( 'X-WP-DeprecatedAbility: %s', $string ) );
+}
+
 /**
  * Handles _doing_it_wrong errors.
  *

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

@@ -408,17 +408,20 @@ public function get_collection_params(): array {
 						'additionalProperties' => true,
 					),
 					'deprecated'  => array(
-						'description'          => __( 'Limit results by deprecation status or details.' ),
+						'description'          => __( 'Limit results by deprecation status or details. Use true to return only deprecated abilities, false to return only active abilities, or an object to match specific deprecation details.' ),
 						'type'                 => array( 'boolean', 'object' ),
 						'properties'           => array(
 							'since'       => array(
-								'type' => 'string',
+								'description' => __( 'Version of the ability provider that deprecated the ability.' ),
+								'type'        => 'string',
 							),
 							'replacement' => array(
-								'type' => 'string',
+								'description' => __( 'Namespaced ability to use instead.' ),
+								'type'        => 'string',
 							),
 							'message'     => array(
-								'type' => 'string',
+								'description' => __( 'Additional migration guidance.' ),
+								'type'        => 'string',
 							),
 						),
 						'additionalProperties' => true,

tests/phpunit/includes/abstract-testcase.php

@@ -760,8 +760,6 @@ public function setExpectedException( $exception, $message = '', $code = null )
 	 */
 	public function deprecated_function_run( $function_name, $replacement, $version, $message = '' ) {
 		if ( ! isset( $this->caught_deprecated[ $function_name ] ) ) {
-			$additional_message = $message;
-
 			switch ( current_action() ) {
 				case 'deprecated_function_run':
 					if ( $replacement ) {
@@ -849,6 +847,8 @@ public function deprecated_function_run( $function_name, $replacement, $version,
 					break;
 
 				case 'deprecated_ability_run':
+					$additional_message = $message;
+
 					if ( $version ) {
 						if ( $replacement ) {
 							$message = sprintf(

tests/phpunit/tests/abilities-api/wpAbility.php

@@ -471,6 +471,21 @@ public function test_meta_deprecated_rejects_invalid_detail(): void {
 		new WP_Ability( self::$test_ability_name, $args );
 	}
 
+	/**
+	 * Tests that the `replacement` detail must be a namespaced ability name.
+	 *
+	 * @ticket 64209
+	 */
+	public function test_meta_deprecated_rejects_invalid_replacement(): void {
+		$args                       = self::$test_ability_properties;
+		$args['meta']['deprecated'] = array( 'replacement' => 'Not An Ability' );
+
+		$this->expectException( InvalidArgumentException::class );
+		$this->expectExceptionMessage( 'The ability deprecation `replacement` value should be a namespaced ability name' );
+
+		new WP_Ability( self::$test_ability_name, $args );
+	}
+
 	/**
 	 * Tests that executing a deprecated ability emits its structured details.
 	 *

tests/phpunit/tests/abilities-api/wpGetAbilities.php

@@ -195,6 +195,30 @@ public function test_deprecated_abilities_can_be_filtered_exclusively(): void {
 		$this->assertArrayHasKey( 'test/deprecated-ability', $result );
 	}
 
+	/**
+	 * Tests that `true` works as a shorthand for any deprecated ability.
+	 *
+	 * @ticket 64209
+	 */
+	public function test_deprecated_abilities_can_be_filtered_with_true_shorthand(): void {
+		$this->simulate_wp_abilities_init();
+
+		$this->register_test_ability( 'test/active-ability' );
+		$this->register_test_ability(
+			'test/deprecated-ability',
+			array(
+				'meta' => array(
+					'deprecated' => array( 'replacement' => 'test/active-ability' ),
+				),
+			)
+		);
+
+		$result = wp_get_abilities( array( 'meta' => array( 'deprecated' => true ) ) );
+
+		$this->assertArrayNotHasKey( 'test/active-ability', $result );
+		$this->assertArrayHasKey( 'test/deprecated-ability', $result );
+	}
+
 	// -------------------------------------------------------------------------
 	// Category filter
 	// -------------------------------------------------------------------------

tests/phpunit/tests/rest-api/wpRestAbilitiesV1ListController.php

@@ -384,6 +384,27 @@ public function test_get_items_can_exclude_deprecated_abilities(): void {
 		$this->assertNotContains( 'test/deprecated-calculator', wp_list_pluck( $response->get_data(), 'name' ) );
 	}
 
+	/**
+	 * Tests that collection discovery can return only deprecated abilities.
+	 *
+	 * @ticket 64209
+	 */
+	public function test_get_items_can_filter_only_deprecated_abilities(): void {
+		$this->register_deprecated_ability();
+
+		$request = new WP_REST_Request( 'GET', '/wp-abilities/v1/abilities' );
+		$request->set_param( 'per_page', 100 );
+		$request->set_param( 'meta', array( 'deprecated' => 'true' ) );
+		$response = $this->server->dispatch( $request );
+
+		$this->assertSame( 200, $response->get_status() );
+
+		$ability_names = wp_list_pluck( $response->get_data(), 'name' );
+
+		$this->assertContains( 'test/deprecated-calculator', $ability_names );
+		$this->assertNotContains( 'test/calculator', $ability_names );
+	}
+
 	/**
 	 * Test getting a specific ability.
 	 *

tests/qunit/fixtures/wp-api-generated.js

@@ -12743,19 +12743,22 @@ mockedApiResponse.Schema = {
                                     "additionalProperties": true
                                 },
                                 "deprecated": {
-                                    "description": "Limit results by deprecation status or details.",
+                                    "description": "Limit results by deprecation status or details. Use true to return only deprecated abilities, false to return only active abilities, or an object to match specific deprecation details.",
                                     "type": [
                                         "boolean",
                                         "object"
                                     ],
                                     "properties": {
                                         "since": {
+                                            "description": "Version of the ability provider that deprecated the ability.",
                                             "type": "string"
                                         },
                                         "replacement": {
+                                            "description": "Namespaced ability to use instead.",
                                             "type": "string"
                                         },
                                         "message": {
+                                            "description": "Additional migration guidance.",
                                             "type": "string"
                                         }
                                     },