diff --git a/src/wp-includes/abilities-api.php b/src/wp-includes/abilities-api.php index 764261d3313a4..3bb05d0cfaf5a 100644 --- a/src/wp-includes/abilities-api.php +++ b/src/wp-includes/abilities-api.php @@ -277,10 +277,22 @@ * 'show_in_rest' => false, * ), * + * Mark an ability as deprecated while keeping exact-name retrieval and execution + * available for backward compatibility: + * + * 'meta' => array( + * 'deprecated' => array( + * 'since' => '2.0.0', + * 'replacement' => 'my-plugin/new-ability', + * 'message' => __( 'The replacement supports the new data format.', 'my-plugin' ), + * ), + * ), + * * @since 6.9.0 * @since 7.1.0 Added the `public` meta argument. * @since 7.2.0 The `category` argument is now optional and defaults to `uncategorized`. * @since 7.2.0 Added the `required_capabilities` argument. + * @since 7.2.0 Added the `deprecated` meta property. * * @see WP_Abilities_Registry::register() * @see WP_Ability::execute() @@ -341,6 +353,15 @@ * clients such as the REST API, MCP, or AI agents. Seeds * the default for per-channel flags like `$show_in_rest`. * Defaults to false. + * @type null|array $deprecated { + * Optional. Deprecation details. If set, mark the ability as deprecated. Deprecated abilities are hidden + * from discovery by default, but can be retrieved by exact name or explicitly included in discovery + * with the `include_deprecated` argument. Default null. + * + * @type string $since Version of the ability provider that deprecated the ability. + * @type string $replacement Optional. Namespaced ability to use instead. + * @type string $message Optional. Additional migration guidance. + * } * @type bool $show_in_rest Optional. Whether to expose this ability in the REST API. * When true, the ability can be invoked via HTTP requests. * Default is the value of `$public` when set, false otherwise. @@ -479,14 +500,14 @@ function wp_get_ability( string $name ): ?WP_Ability { /** * Retrieves registered abilities, optionally filtered by the given arguments. * - * When called without arguments, returns all registered abilities. When called - * with an $args array, returns only abilities that match every specified condition. + * When called without arguments, returns all registered abilities that are not deprecated. + * When called with an $args array, returns only abilities that match every specified condition. * In both cases, the callbacks and filters below can change the result. * * Filtering pipeline (executed in order): * - * 1. Declarative filters (`category`, `namespace`, `meta`, `has_required_capabilities`) — - * per-item, AND logic between arg types. + * 1. Declarative filters (`category`, `include_deprecated`, `namespace`, `meta`, + * `has_required_capabilities`) — per-item, AND logic between arg types. * 2. `item_include_callback` — per-item, caller-scoped. Return true to include, false to exclude. * 3. `wp_get_abilities_item_include` filter — per-item, ecosystem-scoped. Plugins can enforce * inclusion rules for abilities that passed the declarative filters. @@ -497,9 +518,19 @@ function wp_get_ability( string $name ): ?WP_Ability { * * Examples: * - * // All abilities. + * // All (non-deprecated) abilities. * $abilities = wp_get_abilities(); * + * // All abilities, including deprecated ones. + * $abilities = wp_get_abilities( array( + * 'include_deprecated' => true, + * ) ); + * + * // Only deprecated abilities. `true` (or an empty array) matches any deprecation details. + * $abilities = wp_get_abilities( array( + * 'meta' => array( 'deprecated' => true ), + * ) ); + * * // Filter by category. * $abilities = wp_get_abilities( array( 'category' => 'content' ) ); * @@ -544,15 +575,20 @@ function wp_get_ability( string $name ): ?WP_Ability { * @since 6.9.0 * @since 7.1.0 Added the `$args` parameter for filtering support. * @since 7.2.0 Added the `has_required_capabilities` argument. + * @since 7.2.0 Deprecated abilities are excluded by default. Added the `include_deprecated` argument. * * @see WP_Abilities_Registry::get_all_registered() * * @param array $args { * Optional. Arguments to filter the returned abilities. Default empty array. - * Omitted filters do not restrict the results. + * Omitted filters do not restrict the results, except that deprecated abilities + * are excluded unless `include_deprecated` or a `deprecated` meta condition is given. * * @type string $category Optional. Filter by category slug. Only abilities whose category * exactly matches the given slug are included. + * @type bool $include_deprecated Optional. Whether to include deprecated abilities. Deprecated + * abilities retrieved this way do not trigger deprecation notices until + * they are executed. Default false. * @type string $namespace Optional. Filter by ability namespace prefix. Pass the namespace * without a trailing slash, e.g. `'woocommerce'` matches * `'woocommerce/create-order'`. @@ -560,6 +596,8 @@ function wp_get_ability( string $name ): ?WP_Ability { * and non-array values must match strictly, including their types. * Nested arrays are matched recursively as subsets, e.g. * `array( 'mcp' => array( 'public' => true ) )`. + * A `deprecated` condition implies `include_deprecated`. Use + * `true` to match any deprecated ability. * @type bool $has_required_capabilities Optional. Whether to leave out abilities whose required capabilities * the current user doesn't have. Abilities without required * capabilities pass this check but remain subject to other filters. @@ -587,29 +625,40 @@ function wp_get_abilities( array $args = array() ): array { $category = isset( $args['category'] ) && is_string( $args['category'] ) ? $args['category'] : ''; $namespace = isset( $args['namespace'] ) && is_string( $args['namespace'] ) ? rtrim( $args['namespace'], '/' ) . '/' : ''; $meta = isset( $args['meta'] ) && is_array( $args['meta'] ) ? $args['meta'] : array(); + $include_deprecated = ! empty( $args['include_deprecated'] ) || array_key_exists( 'deprecated', $meta ); $has_required_capabilities = ! empty( $args['has_required_capabilities'] ); $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; + // Treat `meta.deprecated` as shorthand for filtering for only deprecated abilities. + if ( isset( $meta['deprecated'] ) && is_bool( $meta['deprecated'] ) ) { + $meta['deprecated'] = $meta['deprecated'] ? array() : null; + } + $matched = array(); foreach ( $abilities as $name => $ability ) { - // Step 1a: Filter by category. + // Step 1a: Exclude deprecated abilities unless requested via `include_deprecated` or a `deprecated` meta condition. + if ( ! $include_deprecated && null !== $ability->get_meta_item( 'deprecated' ) ) { + continue; + } + + // Step 1b: Filter by category. if ( '' !== $category && $ability->get_category() !== $category ) { continue; } - // Step 1b: Filter by namespace prefix. + // Step 1c: Filter by namespace prefix. if ( '' !== $namespace && ! str_starts_with( $ability->get_name(), $namespace ) ) { continue; } - // Step 1c: Filter by meta key/value pairs (AND logic, supports nested arrays). + // Step 1d: Filter by meta key/value pairs (AND logic, supports nested arrays). if ( ! empty( $meta ) && ! _wp_get_abilities_match_meta( $ability->get_meta(), $meta ) ) { continue; } - // Step 1d: Leave out abilities whose required capabilities the current user doesn't have. + // Step 1e: Leave out abilities whose required capabilities the current user doesn't have. if ( $has_required_capabilities ) { foreach ( $ability->get_required_capabilities() as $capability ) { if ( ! current_user_can( $capability ) ) { diff --git a/src/wp-includes/abilities-api/class-wp-abilities-registry.php b/src/wp-includes/abilities-api/class-wp-abilities-registry.php index fe41f8e0f64a7..a3e869e7c02ef 100644 --- a/src/wp-includes/abilities-api/class-wp-abilities-registry.php +++ b/src/wp-includes/abilities-api/class-wp-abilities-registry.php @@ -43,6 +43,7 @@ final class WP_Abilities_Registry { * @since 7.1.0 Added the `public` meta argument. * @since 7.2.0 The `category` argument is now optional and defaults to `uncategorized`. * @since 7.2.0 Added the `required_capabilities` argument. + * @since 7.2.0 Added the `deprecated` meta property. * * @see wp_register_ability() * @@ -83,6 +84,15 @@ final class WP_Abilities_Registry { * to clients such as the REST API, MCP, or AI agents. * Seeds the default for per-channel flags like * `$show_in_rest`. Defaults to false. + * @type null|array $deprecated { + * Optional. Deprecation details. If set, mark the ability as deprecated. Deprecated abilities are hidden + * from discovery by default, but can be retrieved by exact name or explicitly included in discovery + * with the `include_deprecated` argument. Default null. + * + * @type string $since Version of the ability provider that deprecated the ability. + * @type string $replacement Optional. Namespaced ability to use instead. + * @type string $message Optional. Additional migration guidance. + * } * @type bool $show_in_rest Optional. Whether to expose this ability in the REST API. * Default is the value of `$public` when set, false otherwise. * } @@ -121,6 +131,7 @@ public function register( string $name, array $args ): ?WP_Ability { * @since 7.1.0 Added the `public` meta argument. * @since 7.2.0 The `category` argument is now optional and defaults to `uncategorized`. * @since 7.2.0 Added the `required_capabilities` argument. + * @since 7.2.0 Added the `deprecated` meta property. * * @param array $args { * An associative array of arguments for the ability. @@ -147,6 +158,15 @@ public function register( string $name, array $args ): ?WP_Ability { * available to clients such as the REST API, MCP, or AI * agents. Seeds the default for per-channel flags like * `$show_in_rest`. Defaults to false. + * @type null|array $deprecated { + * Optional. Deprecation details. If set, mark the ability as deprecated. Deprecated abilities are hidden + * from discovery by default, but can be retrieved by exact name or explicitly included in discovery + * with the `include_deprecated` argument. Default null. + * + * @type string $since Version of the ability provider that deprecated the ability. + * @type string $replacement Optional. Namespaced ability to use instead. + * @type string $message Optional. Additional migration guidance. + * } * @type bool $show_in_rest Optional. Whether to expose this ability in the REST API. * Default is the value of `$public` when set, false otherwise. * } @@ -279,6 +299,7 @@ public function is_registered( string $name ): bool { * Do not use this method directly. Instead, use the `wp_get_ability()` function. * * @since 6.9.0 + * @since 7.2.0 Added deprecation notices for abilities with the `deprecated` meta property. * * @see wp_get_ability() * @@ -295,7 +316,13 @@ public function get_registered( string $name ): ?WP_Ability { ); return null; } - return $this->registered_abilities[ $name ]; + + $ability = $this->registered_abilities[ $name ]; + + // Check if the ability is deprecated and handle it accordingly. + $ability->_handle_ability_deprecation(); + + return $ability; } /** diff --git a/src/wp-includes/abilities-api/class-wp-ability.php b/src/wp-includes/abilities-api/class-wp-ability.php index a9f53586d4cc5..dbe06217ac4aa 100644 --- a/src/wp-includes/abilities-api/class-wp-ability.php +++ b/src/wp-includes/abilities-api/class-wp-ability.php @@ -149,6 +149,7 @@ class WP_Ability { * @since 6.9.0 * @since 7.1.0 Added the `public` meta argument. * @since 7.2.0 Added the `required_capabilities` argument. + * @since 7.2.0 Added the `deprecated` meta property. * * @see wp_register_ability() * @@ -182,12 +183,21 @@ class WP_Ability { * @type bool|null $idempotent Optional. If true, calling the ability repeatedly with the same arguments * will have no additional effect on its environment. * } - * @type bool $public Optional. Whether the ability is meant to be available - * to clients such as the REST API, MCP, or AI agents. - * Seeds the default for per-channel flags like - * `$show_in_rest`. Defaults to false. - * @type bool $show_in_rest Optional. Whether to expose this ability in the REST API. - * Default is the value of `$public` when set, false otherwise. + * @type null|array $deprecated { + * Optional. Deprecation details. If set, mark the ability as deprecated. Deprecated abilities are hidden + * from discovery by default, but can be retrieved by exact name or explicitly included in discovery + * with the `include_deprecated` argument. Default null. + * + * @type string $since Version of the ability provider that deprecated the ability. + * @type string $replacement Optional. Namespaced ability to use instead. + * @type string $message Optional. Additional migration guidance. + * } + * @type bool $public Optional. Whether the ability is meant to be available + * to clients such as the REST API, MCP, or AI agents. + * Seeds the default for per-channel flags like + * `$show_in_rest`. Defaults to false. + * @type bool $show_in_rest Optional. Whether to expose this ability in the REST API. + * Default is the value of `$public` when set, false otherwise. * } * } */ @@ -225,6 +235,7 @@ public function __construct( string $name, array $args ) { * @since 6.9.0 * @since 7.1.0 Added the `public` meta argument. * @since 7.2.0 Added the `required_capabilities` argument. + * @since 7.2.0 Added support for the `deprecated` meta property. * * @see WP_Abilities_Registry::register() * @@ -257,12 +268,21 @@ public function __construct( string $name, array $args ) { * @type bool|null $idempotent Optional. If true, calling the ability repeatedly with the same arguments * will have no additional effect on its environment. * } - * @type bool $public Optional. Whether the ability is meant to be available - * to clients such as the REST API, MCP, or AI agents. - * Seeds the default for per-channel flags like - * `$show_in_rest`. Defaults to false. - * @type bool $show_in_rest Optional. Whether to expose this ability in the REST API. - * Default is the value of `$public` when set, false otherwise. + * @type null|array $deprecated { + * Optional. Deprecation details. If set, mark the ability as deprecated. Deprecated abilities are hidden + * from discovery by default, but can be retrieved by exact name or explicitly included in discovery + * with the `include_deprecated` argument. Default null. + * + * @type string $since Version of the ability provider that deprecated the ability. + * @type string $replacement Optional. Namespaced ability to use instead. + * @type string $message Optional. Additional migration guidance. + * } + * @type bool $public Optional. Whether the ability is meant to be available + * to clients such as the REST API, MCP, or AI agents. + * Seeds the default for per-channel flags like + * `$show_in_rest`. Defaults to false. + * @type bool $show_in_rest Optional. Whether to expose this ability in the REST API. + * Default is the value of `$public` when set, false otherwise. * } * } * @return array { @@ -294,10 +314,17 @@ public function __construct( string $name, array $args ) { * @type bool|null $idempotent If true, calling the ability repeatedly with the same arguments * will have no additional effect on its environment. * } - * @type bool $public Whether the ability is meant to be available to clients - * such as the REST API, MCP, or AI agents. Defaults to - * false. - * @type bool $show_in_rest Whether to expose this ability in the REST API. + * @type bool $public Whether the ability is meant to be available to clients + * such as the REST API, MCP, or AI agents. Defaults to + * false. + * @type null|array $deprecated { + * Deprecation details, or null when the ability is not deprecated. + * + * @type string $since Version of the ability provider that deprecated the ability. + * @type string $replacement Optional. Namespaced ability to use instead. + * @type string $message Optional. Additional migration guidance. + * } + * @type bool $show_in_rest Whether to expose this ability in the REST API. * } * } * @throws InvalidArgumentException if an argument is invalid. @@ -390,6 +417,35 @@ protected function prepare_properties( array $args ): array { ); } + if ( isset( $args['meta']['deprecated'] ) ) { + if ( ! is_array( $args['meta']['deprecated'] ) ) { + throw new InvalidArgumentException( + __( 'The ability meta should provide `deprecated` as null or an array of deprecation details.' ) + ); + } + + foreach ( array( 'since', 'replacement', 'message' ) as $key ) { + if ( ! isset( $key, $args['meta']['deprecated'] ) ) { + if ( 'since' === $key ) { + throw new InvalidArgumentException( + __( 'The ability deprecation details must include a `since` version.' ) + ); + } + continue; + } + + if ( ! is_string( $args['meta']['deprecated'][ $key ] ) || '' === $args['meta']['deprecated'][ $key ] ) { + throw new InvalidArgumentException( + sprintf( + /* translators: %s: Deprecation metadata key. */ + __( 'The ability deprecation `%s` value should be a non-empty string.' ), + $key + ) + ); + } + } + } + $args['required_capabilities'] ??= array(); // Set defaults for optional meta. @@ -412,6 +468,7 @@ protected function prepare_properties( array $args ): array { */ $args['meta']['show_in_rest'] ??= $args['meta']['public'] ?? self::DEFAULT_SHOW_IN_REST; $args['meta']['public'] ??= self::DEFAULT_PUBLIC; + $args['meta']['deprecated'] ??= null; return $args; } @@ -942,6 +999,9 @@ protected function validate_output( $output ) { * @return mixed|WP_Error The result of the ability execution, or WP_Error on failure. */ public function execute( $input = null ) { + // Triggers a deprecation notice if the ability is marked as deprecated and hasn't been triggered earlier. + $this->_handle_ability_deprecation(); + /** * Fires when an ability is invoked, before any processing takes place. * @@ -1057,6 +1117,84 @@ public function execute( $input = null ) { return $result; } + /** + * Informs when a deprecated ability has been called. + * + * There is a {@see 'deprecated_ability_run'} hook that will be called that can be used + * to get the backtrace up to what file and function used the deprecated ability. + * + * The current behavior is to trigger a user error if `WP_DEBUG` is true. + * + * @since 7.2.0 + * @internal Triggered when a deprecated ability is called. It should never be called directly in user + * code. There is no guarantee of backward compatibility. + */ + public function _handle_ability_deprecation(): void { + $name = $this->get_name(); + $deprecation_meta = $this->get_meta_item( 'deprecated' ); + if ( ! is_array( $deprecation_meta ) || ! isset( $deprecation_meta['since'] ) ) { + return; + } + + $version = $deprecation_meta['since']; + $replacement = $deprecation_meta['replacement'] ?? ''; + $message = $deprecation_meta['message'] ?? ''; + + /** + * Fires every time a deprecated ability is called. + * + * @since 7.2.0 + * + * @param string $ability_name The ability that was retrieved. + * @param string $replacement The ability that should be used as a replacement. + * @param string $version The version of the ability provider (plugin, WordPress core, etc.) that deprecated the ability. + * @param string $message Additional migration guidance. + */ + do_action( 'deprecated_ability_run', $name, $replacement, $version, $message ); + + // A local cache of deprecated abilities is used to prevent repeated warnings. + static $deprecated_abilities = array(); + + $already_triggered = isset( $deprecated_abilities[ $name ] ); + + /** + * Filters whether to trigger an error for deprecated abilities. + * + * @since 7.2.0 + * + * @param bool $trigger Whether to trigger the error for deprecated abilities. + * Default true if the warning has not already been triggered for this ability, false on + * subsequent calls. + */ + if ( WP_DEBUG && apply_filters( 'deprecated_ability_trigger_error', ! $already_triggered ) ) { + $message = empty( $message ) ? '' : ' ' . $message; + + if ( $replacement ) { + $notice = sprintf( + /* translators: 1: Ability name, 2: Version number, 3: Alternative ability name, 4: Additional message. */ + __( 'Ability %1$s is deprecated since version %2$s. Use %3$s instead.%4$s' ), + $name, + $version, + $replacement, + $message + ); + } else { + $notice = sprintf( + /* translators: 1: Ability name, 2: Version number, 3: Additional message. */ + __( 'Ability %1$s is deprecated since version %2$s with no alternative available.%3$s' ), + $name, + $version, + $message + ); + } + + wp_trigger_error( '', $notice, E_USER_DEPRECATED ); + + // Store the deprecated ability so we don't spam the same warning multiple times. + $deprecated_abilities[ $name ] = true; + } + } + /** * Wakeup magic method. * diff --git a/src/wp-includes/rest-api.php b/src/wp-includes/rest-api.php index f40021f4d06cd..9281bc3ff9c05 100644 --- a/src/wp-includes/rest-api.php +++ b/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' ); } @@ -777,6 +779,36 @@ function rest_handle_deprecated_argument( $function_name, $message, $version ) { header( sprintf( 'X-WP-DeprecatedParam: %s', $string ) ); } +/** + * Handles deprecated ability notices. + * + * @since 7.2.0 + * + * @param string $ability_name The deprecated ability that was used. + * @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 ( $replacement ) { + /* translators: Developer debugging message. 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 ); + } else { + /* translators: Developer debugging message. 1: Ability name, 2: Version number. */ + $string = sprintf( __( '%1$s (since %2$s; no alternative available)' ), $ability_name, $version ); + } + + if ( $message ) { + $string .= ' ' . $message; + } + + header( sprintf( 'X-WP-DeprecatedAbility: %s', $string ) ); +} + /** * Handles _doing_it_wrong errors. * diff --git a/src/wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-list-controller.php b/src/wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-list-controller.php index da2bb71fc51fd..45939cf7bd608 100644 --- a/src/wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-list-controller.php +++ b/src/wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-list-controller.php @@ -81,6 +81,7 @@ public function register_routes(): void { * Retrieves all abilities. * * @since 6.9.0 + * @since 7.2.0 Added support for the `include_deprecated` parameter. * * @param WP_REST_Request $request Full details about the request. * @return WP_REST_Response Response object on success. @@ -98,6 +99,10 @@ public function get_items( $request ) { $query_args['namespace'] = $request['namespace']; } + if ( ! empty( $request['include_deprecated'] ) ) { + $query_args['include_deprecated'] = true; + } + if ( ! empty( $request['meta'] ) ) { // Merge caller meta first so the forced show_in_rest filter wins. This keeps a caller from using meta to reveal abilities hidden from REST. $query_args['meta'] = array_merge( $request['meta'], $query_args['meta'] ); @@ -251,6 +256,7 @@ public function prepare_item_for_response( $ability, $request ) { * @since 6.9.0 * @since 7.1.0 Added the `meta.public` property. * @since 7.2.0 Added the `required_capabilities` property. + * @since 7.2.0 Added the `deprecated` meta property to the ability schema. * * @return array Item schema data. */ @@ -332,6 +338,24 @@ public function get_item_schema(): array { 'description' => __( 'Whether the ability is meant to be available to clients such as the REST API, MCP, or AI agents. Defaults to false, but individual channel settings such as show_in_rest can override it.' ), 'type' => 'boolean', ), + 'deprecated' => array( + 'description' => __( 'Deprecation details for the ability, or null when the ability is not deprecated.' ), + 'type' => array( 'null', 'object' ), + 'properties' => array( + 'since' => array( + 'description' => __( 'Version of the ability provider that deprecated the ability.' ), + 'type' => 'string', + ), + 'replacement' => array( + 'description' => __( 'Namespaced ability to use instead.' ), + 'type' => 'string', + ), + 'message' => array( + 'description' => __( 'Additional migration guidance.' ), + 'type' => 'string', + ), + ), + ), ), 'context' => array( 'view', 'edit' ), 'readonly' => true, @@ -348,6 +372,7 @@ public function get_item_schema(): array { * @since 6.9.0 * @since 7.1.0 Added the `namespace` and `meta` parameters and the `rest_abilities_collection_params` filter. * @since 7.2.0 Added the `has_required_capabilities` parameter. + * @since 7.2.0 Added the `include_deprecated` parameter. * * @return array Collection parameters. */ @@ -373,6 +398,12 @@ public function get_collection_params(): array { 'sanitize_callback' => 'sanitize_key', 'validate_callback' => 'rest_validate_request_arg', ), + 'include_deprecated' => array( + 'description' => __( 'Whether to include deprecated abilities in the results.' ), + 'type' => 'boolean', + 'sanitize_callback' => 'rest_sanitize_boolean', + 'validate_callback' => 'rest_validate_request_arg', + ), 'namespace' => array( 'description' => __( 'Limit results to abilities in a specific namespace.' ), 'type' => 'string', @@ -403,6 +434,24 @@ public function get_collection_params(): array { ), 'additionalProperties' => true, ), + 'deprecated' => array( + 'description' => __( 'Limit results to deprecated abilities matching the given details. Use true for any deprecated ability, or false for active abilities only.' ), + 'type' => array( 'boolean', 'object' ), + 'properties' => array( + 'since' => array( + 'description' => __( 'Version of the ability provider that deprecated the ability.' ), + 'type' => 'string', + ), + 'replacement' => array( + 'description' => __( 'Namespaced ability to use instead.' ), + 'type' => 'string', + ), + 'message' => array( + 'description' => __( 'Additional migration guidance.' ), + 'type' => 'string', + ), + ), + ), ), 'additionalProperties' => true, ), diff --git a/tests/phpunit/includes/abstract-testcase.php b/tests/phpunit/includes/abstract-testcase.php index 4b343666819db..3ed28e4b969a7 100644 --- a/tests/phpunit/includes/abstract-testcase.php +++ b/tests/phpunit/includes/abstract-testcase.php @@ -742,6 +742,7 @@ public function expectDeprecated() { add_action( 'deprecated_class_run', array( $this, 'deprecated_function_run' ), 10, 3 ); add_action( 'deprecated_file_included', array( $this, 'deprecated_function_run' ), 10, 4 ); add_action( 'deprecated_hook_run', array( $this, 'deprecated_function_run' ), 10, 4 ); + add_action( 'deprecated_ability_run', array( $this, 'deprecated_function_run' ), 10, 4 ); add_action( 'doing_it_wrong_run', array( $this, 'doing_it_wrong_run' ), 10, 3 ); add_action( 'deprecated_function_trigger_error', '__return_false' ); @@ -749,6 +750,7 @@ public function expectDeprecated() { add_action( 'deprecated_class_trigger_error', '__return_false' ); add_action( 'deprecated_file_trigger_error', '__return_false' ); add_action( 'deprecated_hook_trigger_error', '__return_false' ); + add_action( 'deprecated_ability_trigger_error', '__return_false' ); add_action( 'doing_it_wrong_trigger_error', '__return_false' ); } @@ -1005,6 +1007,28 @@ public function deprecated_function_run( $function_name, $replacement, $version, ) . ' ' . $message; } break; + + case 'deprecated_ability_run': + $additional_message = $message; + + if ( $replacement ) { + $message = sprintf( + 'Ability %1$s is deprecated since version %2$s. Use %3$s instead.', + $function_name, + $version, + $replacement + ); + } else { + $message = sprintf( + 'Ability %1$s is deprecated since version %2$s with no alternative available.', + $function_name, + $version + ); + } + if ( $additional_message ) { + $message .= ' ' . $additional_message; + } + break; } $this->caught_deprecated[ $function_name ] = $message; diff --git a/tests/phpunit/tests/abilities-api/wpAbilitiesRegistry.php b/tests/phpunit/tests/abilities-api/wpAbilitiesRegistry.php index b29bbe38a27f7..53878a21fde06 100644 --- a/tests/phpunit/tests/abilities-api/wpAbilitiesRegistry.php +++ b/tests/phpunit/tests/abilities-api/wpAbilitiesRegistry.php @@ -582,6 +582,50 @@ public function test_get_registered_for_known_ability() { $this->assertSame( 'test/two', $result->get_name() ); } + /** + * Should trigger the deprecation notice when retrieving a deprecated ability by name. + * + * @ticket 64209 + * + * @covers WP_Abilities_Registry::register + * @covers WP_Abilities_Registry::get_registered + * @covers WP_Ability::_handle_ability_deprecation + */ + public function test_get_registered_triggers_deprecation_for_deprecated_ability() { + $deprecated_args = self::$test_ability_args; + $deprecated_args['meta']['deprecated'] = array( + 'since' => '2.0.0', + 'replacement' => 'test/one', + 'message' => 'Use the new input format.', + ); + $this->registry->register( 'test/one', self::$test_ability_args ); + $this->registry->register( 'test/deprecated', $deprecated_args ); + + $received = null; + $listener = static function ( $name, $replacement, $version, $message ) use ( &$received ): void { + $received = compact( 'name', 'replacement', 'version', 'message' ); + }; + + $this->setExpectedDeprecated( 'test/deprecated' ); + add_action( 'deprecated_ability_run', $listener, 10, 4 ); + + $result = $this->registry->get_registered( 'test/deprecated' ); + + remove_action( 'deprecated_ability_run', $listener, 10 ); + + $this->assertSame( 'test/deprecated', $result->get_name() ); + $this->assertSame( + array( + 'name' => 'test/deprecated', + 'replacement' => 'test/one', + 'version' => '2.0.0', + 'message' => 'Use the new input format.', + ), + $received, + 'Retrieving a deprecated ability by exact name should emit its structured deprecation details.' + ); + } + /** * Unregistering should fail if an ability is not registered. * diff --git a/tests/phpunit/tests/abilities-api/wpAbility.php b/tests/phpunit/tests/abilities-api/wpAbility.php index 8fdb67e29cd7f..8baa4015fc359 100644 --- a/tests/phpunit/tests/abilities-api/wpAbility.php +++ b/tests/phpunit/tests/abilities-api/wpAbility.php @@ -381,6 +381,127 @@ public function test_meta_public_throws_exception_for_non_boolean() { new WP_Ability( self::$test_ability_name, $args ); } + /** + * Tests that `deprecated` rejects values other than an array. + * + * @ticket 64209 + */ + public function test_meta_deprecated_rejects_invalid_type(): void { + $args = self::$test_ability_properties; + $args['meta']['deprecated'] = true; + + $this->expectException( InvalidArgumentException::class ); + $this->expectExceptionMessage( 'The ability meta should provide `deprecated` as null or an array of deprecation details.' ); + + new WP_Ability( self::$test_ability_name, $args ); + } + + /** + * Data provider for deprecation details that must include a `since` version. + * + * @return array Data sets. + */ + public function data_meta_deprecated_requires_since(): array { + return array( + 'no details' => array( array() ), + 'null since' => array( array( 'since' => null ) ), + 'replacement + message' => array( + array( + 'replacement' => 'test/new-calculator', + 'message' => 'Use the new input format.', + ), + ), + ); + } + + /** + * Tests that `deprecated` details must always include a `since` version. + * + * @ticket 64209 + * + * @dataProvider data_meta_deprecated_requires_since + * + * @param array $deprecated The deprecation details under test. + */ + public function test_meta_deprecated_rejects_details_without_since( array $deprecated ): void { + $args = self::$test_ability_properties; + $args['meta']['deprecated'] = $deprecated; + + $this->expectException( InvalidArgumentException::class ); + $this->expectExceptionMessage( 'The ability deprecation details must include a `since` version.' ); + + new WP_Ability( self::$test_ability_name, $args ); + } + + /** + * Data provider for supported `deprecated` details with invalid values. + * + * @return array Data sets. + */ + public function data_meta_deprecated_rejects_invalid_detail(): array { + return array( + 'integer since' => array( + array( 'since' => 2 ), + 'since', + ), + 'integer replacement' => array( + array( + 'since' => '2.0.0', + 'replacement' => 5, + ), + 'replacement', + ), + 'empty replacement' => array( + array( + 'since' => '2.0.0', + 'replacement' => '', + ), + 'replacement', + ), + ); + } + + /** + * Tests that supported `deprecated` details must be non-empty strings. + * + * @ticket 64209 + * + * @dataProvider data_meta_deprecated_rejects_invalid_detail + * + * @param array $deprecated The deprecation details under test. + * @param string $key The detail key holding the invalid value. + */ + public function test_meta_deprecated_rejects_invalid_detail( array $deprecated, string $key ): void { + $args = self::$test_ability_properties; + $args['meta']['deprecated'] = $deprecated; + + $this->expectException( InvalidArgumentException::class ); + $this->expectExceptionMessage( sprintf( 'The ability deprecation `%s` value should be a non-empty string.', $key ) ); + + new WP_Ability( self::$test_ability_name, $args ); + } + + /** + * Tests that executing a deprecated ability emits a deprecation notice. + * + * Covers abilities that were retrieved without a notice, e.g. via `wp_get_abilities()`. + * + * @ticket 64209 + * + * @covers WP_Ability::execute + * @covers WP_Ability::_handle_ability_deprecation + */ + public function test_execute_deprecated_ability_emits_deprecation(): void { + $args = self::$test_ability_properties; + $args['meta']['deprecated'] = array( 'since' => '2.0.0' ); + + $this->setExpectedDeprecated( self::$test_ability_name ); + + $ability = new WP_Ability( self::$test_ability_name, $args ); + + $this->assertSame( 0, $ability->execute() ); + } + /** * Data provider for testing the execution of the ability. * diff --git a/tests/phpunit/tests/abilities-api/wpGetAbilities.php b/tests/phpunit/tests/abilities-api/wpGetAbilities.php index 3618a4070bc34..764539a147384 100644 --- a/tests/phpunit/tests/abilities-api/wpGetAbilities.php +++ b/tests/phpunit/tests/abilities-api/wpGetAbilities.php @@ -115,6 +115,231 @@ private function register_test_ability( string $name, array $overrides = array() return $ability; } + // ------------------------------------------------------------------------- + // Deprecated abilities + // ------------------------------------------------------------------------- + + /** + * Tests that deprecated abilities are excluded from discovery by default. + * + * @ticket 64209 + */ + public function test_deprecated_abilities_are_excluded_by_default(): 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( + 'since' => '2.0.0', + 'replacement' => 'test/active-ability', + ), + ), + ) + ); + + $result = wp_get_abilities(); + + $this->assertArrayHasKey( 'test/active-ability', $result ); + $this->assertArrayNotHasKey( 'test/deprecated-ability', $result ); + } + + /** + * Tests that deprecated abilities can be included in discovery. + * + * @ticket 64209 + */ + public function test_deprecated_abilities_can_be_included_in_discovery(): 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( + 'since' => '2.0.0', + 'replacement' => 'test/active-ability', + ), + ), + ) + ); + + $result = wp_get_abilities( array( 'include_deprecated' => true ) ); + + $this->assertArrayHasKey( 'test/active-ability', $result ); + $this->assertArrayHasKey( 'test/deprecated-ability', $result ); + } + + /** + * Tests that a `deprecated` meta condition returns only deprecated abilities. + * + * A `deprecated` meta condition implies `include_deprecated`, and an empty array + * matches any deprecation details. + * + * @ticket 64209 + */ + public function test_deprecated_abilities_can_be_filtered_exclusively(): 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( + 'since' => '2.0.0', + 'replacement' => 'test/active-ability', + ), + ), + ) + ); + + $result = wp_get_abilities( + array( + 'meta' => array( 'deprecated' => array() ), + ) + ); + + $this->assertArrayNotHasKey( 'test/active-ability', $result ); + $this->assertArrayHasKey( 'test/deprecated-ability', $result ); + } + + /** + * Tests that a null `deprecated` meta condition returns only active abilities. + * + * @ticket 64209 + */ + public function test_deprecated_null_condition_matches_active_abilities(): 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( + 'since' => '2.0.0', + 'replacement' => 'test/active-ability', + ), + ), + ) + ); + + $result = wp_get_abilities( + array( + 'meta' => array( 'deprecated' => null ), + ) + ); + + $this->assertArrayHasKey( 'test/active-ability', $result ); + $this->assertArrayNotHasKey( 'test/deprecated-ability', $result ); + } + + /** + * Tests that a `true` `deprecated` meta condition returns only deprecated abilities. + * + * @ticket 64209 + */ + public function test_deprecated_true_condition_matches_deprecated_abilities(): 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( + 'since' => '2.0.0', + '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 ); + } + + /** + * Tests that a `false` `deprecated` meta condition returns only active abilities. + * + * @ticket 64209 + */ + public function test_deprecated_false_condition_matches_active_abilities(): 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( + 'since' => '2.0.0', + 'replacement' => 'test/active-ability', + ), + ), + ) + ); + + $result = wp_get_abilities( + array( + 'include_deprecated' => true, + 'meta' => array( 'deprecated' => false ), + ) + ); + + $this->assertArrayHasKey( 'test/active-ability', $result ); + $this->assertArrayNotHasKey( 'test/deprecated-ability', $result ); + } + + /** + * Tests that a `deprecated` meta condition can match specific deprecation details. + * + * @ticket 64209 + */ + public function test_deprecated_abilities_can_be_filtered_by_details(): void { + $this->simulate_wp_abilities_init(); + + $this->register_test_ability( 'test/active-ability' ); + $this->register_test_ability( + 'test/deprecated-since-two', + array( + 'meta' => array( + 'deprecated' => array( 'since' => '2.0.0' ), + ), + ) + ); + $this->register_test_ability( + 'test/deprecated-since-three', + array( + 'meta' => array( + 'deprecated' => array( 'since' => '3.1.0' ), + ), + ) + ); + + $result = wp_get_abilities( + array( + 'meta' => array( + 'deprecated' => array( 'since' => '2.0.0' ), + ), + ) + ); + + $this->assertArrayNotHasKey( 'test/active-ability', $result ); + $this->assertArrayHasKey( 'test/deprecated-since-two', $result ); + $this->assertArrayNotHasKey( 'test/deprecated-since-three', $result ); + } + // ------------------------------------------------------------------------- // Category filter // ------------------------------------------------------------------------- diff --git a/tests/phpunit/tests/abilities-api/wpRegisterAbility.php b/tests/phpunit/tests/abilities-api/wpRegisterAbility.php index 4c54eeeb2163f..c20bcabb431eb 100644 --- a/tests/phpunit/tests/abilities-api/wpRegisterAbility.php +++ b/tests/phpunit/tests/abilities-api/wpRegisterAbility.php @@ -196,6 +196,7 @@ public function test_register_valid_ability(): void { 'annotations' => $expected_annotations, 'show_in_rest' => true, 'public' => false, + 'deprecated' => null, ) ); diff --git a/tests/phpunit/tests/rest-api/wpRestAbilitiesV1ListController.php b/tests/phpunit/tests/rest-api/wpRestAbilitiesV1ListController.php index 3d07d4212f28b..df15d6c12332a 100644 --- a/tests/phpunit/tests/rest-api/wpRestAbilitiesV1ListController.php +++ b/tests/phpunit/tests/rest-api/wpRestAbilitiesV1ListController.php @@ -76,7 +76,7 @@ public function set_up(): void { */ public function tear_down(): void { // Clean up test abilities. - foreach ( wp_get_abilities() as $ability ) { + foreach ( wp_get_abilities( array( 'include_deprecated' => true ) ) as $ability ) { if ( ! str_starts_with( $ability->get_name(), 'test/' ) ) { continue; } @@ -166,6 +166,29 @@ private function register_featured_ability(): void { ); } + /** + * Helper to register a deprecated ability exposed through REST. + */ + private function register_deprecated_ability(): void { + $this->register_test_ability( + 'test/deprecated-calculator', + array( + 'label' => 'Deprecated Calculator', + 'description' => 'A deprecated calculator ability.', + 'category' => 'math', + 'execute_callback' => '__return_true', + 'permission_callback' => '__return_true', + 'meta' => array( + 'show_in_rest' => true, + 'deprecated' => array( + 'since' => '2.0.0', + 'replacement' => 'test/calculator', + ), + ), + ) + ); + } + /** * Register test abilities for testing. */ @@ -318,6 +341,139 @@ public function test_get_items(): void { $this->assertNotContains( 'test/not-show-in-rest', $ability_names ); } + /** + * Tests that collection discovery excludes deprecated abilities by default. + * + * @ticket 64209 + */ + public function test_get_items_excludes_deprecated_abilities_by_default(): void { + $this->register_deprecated_ability(); + + $request = new WP_REST_Request( 'GET', '/wp-abilities/v1/abilities' ); + $request->set_param( 'per_page', 100 ); + $response = $this->server->dispatch( $request ); + + $this->assertSame( 200, $response->get_status() ); + + $ability_names = wp_list_pluck( $response->get_data(), 'name' ); + + $this->assertContains( 'test/calculator', $ability_names ); + $this->assertNotContains( 'test/deprecated-calculator', $ability_names ); + } + + /** + * Tests that the `include_deprecated` parameter adds deprecated abilities to the collection. + * + * @ticket 64209 + */ + public function test_get_items_include_deprecated(): void { + $this->register_deprecated_ability(); + + $request = new WP_REST_Request( 'GET', '/wp-abilities/v1/abilities' ); + $request->set_param( 'per_page', 100 ); + $request->set_param( 'include_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/calculator', $ability_names ); + $this->assertContains( 'test/deprecated-calculator', $ability_names ); + } + + /** + * Tests that a `deprecated` meta filter returns matching deprecated abilities in the collection. + * + * @ticket 64209 + */ + public function test_get_items_deprecated_meta_filter_returns_matching_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' => array( 'since' => '2.0.0' ) ) ); + $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 ); + } + + /** + * Tests that the boolean `deprecated` meta shorthand filters the collection by deprecation status. + * + * @ticket 64209 + */ + public function test_get_items_deprecated_meta_boolean_shorthand(): 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 ); + + $request->set_param( 'meta', array( 'deprecated' => false ) ); + $response = $this->server->dispatch( $request ); + + $this->assertSame( 200, $response->get_status() ); + + $ability_names = wp_list_pluck( $response->get_data(), 'name' ); + + $this->assertNotContains( 'test/deprecated-calculator', $ability_names ); + $this->assertContains( 'test/calculator', $ability_names ); + } + + /** + * Tests that an invalid `deprecated` meta filter is rejected. + * + * @ticket 64209 + */ + public function test_get_items_deprecated_meta_invalid_value(): void { + $request = new WP_REST_Request( 'GET', '/wp-abilities/v1/abilities' ); + $request->set_param( 'meta', array( 'deprecated' => 'yes-please' ) ); + $response = $this->server->dispatch( $request ); + + $this->assertSame( 400, $response->get_status() ); + $this->assertSame( 'rest_invalid_param', $response->get_data()['code'] ); + } + + /** + * Tests that the deprecated abilities remain retrievable through their exact REST route. + * + * @ticket 64209 + */ + public function test_get_item_deprecated_ability_by_exact_name(): void { + $this->register_deprecated_ability(); + + $this->setExpectedDeprecated( 'test/deprecated-calculator' ); + + $request = new WP_REST_Request( 'GET', '/wp-abilities/v1/abilities/test/deprecated-calculator' ); + $response = $this->server->dispatch( $request ); + + $this->assertSame( 200, $response->get_status() ); + + $data = $response->get_data(); + $this->assertSame( 'test/deprecated-calculator', $data['name'] ); + $this->assertSame( + array( + 'since' => '2.0.0', + 'replacement' => 'test/calculator', + ), + $data['meta']['deprecated'] + ); + } + /** * Test getting a specific ability. * diff --git a/tests/phpunit/tests/rest-api/wpRestAbilitiesV1RunController.php b/tests/phpunit/tests/rest-api/wpRestAbilitiesV1RunController.php index 3f89d742b9da2..a91a5f39c250a 100644 --- a/tests/phpunit/tests/rest-api/wpRestAbilitiesV1RunController.php +++ b/tests/phpunit/tests/rest-api/wpRestAbilitiesV1RunController.php @@ -87,7 +87,7 @@ public function set_up(): void { */ public function tear_down(): void { // Clean up test abilities. - foreach ( wp_get_abilities() as $ability ) { + foreach ( wp_get_abilities( array( 'include_deprecated' => true ) ) as $ability ) { if ( ! str_starts_with( $ability->get_name(), 'test/' ) ) { continue; } @@ -608,6 +608,41 @@ public function test_execute_regular_ability_post(): void { $this->assertSame( 8.0, $response->get_data() ); } + /** + * Tests that deprecated abilities remain executable through their exact REST route. + * + * @ticket 64209 + */ + public function test_execute_deprecated_ability_by_exact_name(): void { + $this->register_test_ability( + 'test/deprecated-ability', + array( + 'label' => 'Deprecated Ability', + 'description' => 'A deprecated test ability.', + 'category' => 'general', + 'execute_callback' => static function (): string { + return 'executed'; + }, + 'permission_callback' => '__return_true', + 'meta' => array( + 'show_in_rest' => true, + 'deprecated' => array( + 'since' => '2.0.0', + 'replacement' => 'test/calculator', + ), + ), + ) + ); + + $this->setExpectedDeprecated( 'test/deprecated-ability' ); + + $request = new WP_REST_Request( 'POST', '/wp-abilities/v1/abilities/test/deprecated-ability/run' ); + $response = $this->server->dispatch( $request ); + + $this->assertSame( 200, $response->get_status() ); + $this->assertSame( 'executed', $response->get_data() ); + } + /** * Test executing a read-only ability with GET. * diff --git a/tests/qunit/fixtures/wp-api-generated.js b/tests/qunit/fixtures/wp-api-generated.js index 807eda9d2cf92..3211b2c9cc048 100644 --- a/tests/qunit/fixtures/wp-api-generated.js +++ b/tests/qunit/fixtures/wp-api-generated.js @@ -12749,6 +12749,11 @@ mockedApiResponse.Schema = { "type": "string", "required": false }, + "include_deprecated": { + "description": "Whether to include deprecated abilities in the results.", + "type": "boolean", + "required": false + }, "namespace": { "description": "Limit results to abilities in a specific namespace.", "type": "string",