Changeset 65306

Timestamp:

11/06/2026 08:36:45 AM (less than one hour ago)

Author:

gziolo

Message:

Abilities API: Document input preparation for direct permission checks

WP_Ability::check_permissions() does not prepare the input. Callers outside of WP_Ability::execute() must run normalize_input(), validate_input(), and coerce_input() first, or the permission callback may get different input than during execute().

Developed in ​https://github.com/WordPress/wordpress-develop/pull/15514.

Props euvoor, gziolo, zaguiini, jorbin.
See #66482.

Location:

trunk/src/wp-includes

Files:

• abilities-api.php (modified) (4 diffs)
• abilities-api/class-wp-ability.php (modified) (4 diffs)

trunk/src/wp-includes/abilities-api.php

@@ -200 +200 @@
  *
  * The execute callback performs the ability's core functionality. It receives
- * the normalized, validated input when an input schema is defined, and no arguments
- * otherwise. It returns either a result or `WP_Error` on failure. Exceptions thrown
- * by execute or permission callbacks are caught and converted to a `WP_Error`.
+ * the normalized, validated, and coerced input when an input schema is defined,
+ * and no arguments otherwise. It returns either a result or `WP_Error` on failure.
+ * Exceptions thrown by execute or permission callbacks are caught and converted
+ * to a `WP_Error`.
  *
  *     function my_plugin_analyze_text( string $input ): string|WP_Error {
@@ -225 +226 @@
  * with no required capabilities.
  *
- * The permission callback determines whether the ability can be executed.
- * It receives the same input as the execute callback and must return a
- * boolean or `WP_Error`. Common use cases include checking user capabilities,
- * validating API keys, or verifying system state. In the example above, every
- * execution requires `edit_posts`, and the callback only adds the check that
- * depends on the input:
+ * The permission callback determines whether the ability can be executed and
+ * must return a boolean or `WP_Error`. When called through `WP_Ability::execute()`,
+ * it receives the same normalized, validated, and coerced input as the execute
+ * callback. Common use cases include checking user capabilities, validating API
+ * keys, or verifying system state. In the example above, every execution requires
+ * `edit_posts`, and the callback only adds the check that depends on the input:
  *
  *     function my_plugin_can_analyze_text( string $input ): bool|WP_Error {
@@ -242 +243 @@
  * ### Execution Lifecycle
  *
- * Call `WP_Ability::execute()` to normalize and validate input, check permissions,
- * invoke the execute callback, and validate output. It returns the result or a
- * `WP_Error` on failure. Custom ability classes can override this behavior.
+ * Call `WP_Ability::execute()` to normalize, validate, and coerce input, check
+ * permissions, invoke the execute callback, and validate output. It returns the
+ * result or a `WP_Error` on failure. Custom ability classes can override this
+ * behavior.
+ *
+ * Integrations that call `WP_Ability::check_permissions()` directly must prepare
+ * the input first. See `WP_Ability::check_permissions()` for the required steps.
  *
  * Hooks run in this order, and processing stops at the first failure:
@@ -252 +257 @@
  *  3. `wp_ability_normalize_input`, `wp_ability_validate_input`, and
  *     `wp_ability_permission_result` filters. The input validation filter runs only
- *     when a non-empty input schema is defined.
+ *     when a non-empty input schema is defined. Input coercion has no filter. It runs
+ *     between validation and the permission check, only when a non-empty input
+ *     schema is defined.
  *  4. `wp_before_execute_ability` action.
  *  5. `wp_ability_execute_result` and `wp_ability_validate_output` filters.

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

@@ -567 +567 @@
          *
          * Also applies schema format sanitization, such as stripping tags for
-         * `text-field` and sanitizing URLs for `uri`, using rest_sanitize_value_from_schema().
-         *
-         * Call validate_input() before this method. Coercing unvalidated input can
+         * `text-field` and sanitizing URLs for `uri`, using `rest_sanitize_value_from_schema()`.
+         *
+         * Call `validate_input()` before this method. Coercing unvalidated input can
          * remove unknown properties or cast invalid values, hiding validation errors.
          * This method does not apply defaults or run input validation filters.
@@ -578 +578 @@
          * @since 7.2.0
          *
-         * @see validate_input()
+         * @see WP_Ability::validate_input()
          *
          * @param mixed $input Validated ability input.
-         * @return mixed|WP_Error Coerced input, or WP_Error when it cannot be safely coerced.
+         * @return mixed|WP_Error Coerced input, or `WP_Error` when it cannot be safely coerced.
          */
         public function coerce_input( $input ) {
@@ -752 +752 @@
          * Checks whether the ability has the necessary permissions.
          *
-         * Please note that input is not automatically validated against the input schema.
-         * Use `validate_input()` method to validate input before calling this method if needed.
+         * This method does not prepare the input. Use `execute()` to run the full ability
+         * lifecycle, which prepares the input before calling this method.
+         *
+         * When calling this method directly, prepare the input in the same order as
+         * `execute()`, and stop if any step returns a `WP_Error`:
+         *
+         *  1. `normalize_input()` applies the schema default and returns the input.
+         *  2. `validate_input()` checks the input against the schema and returns `true`.
+         *  3. `coerce_input()` converts values to the schema types and returns the input
+         *     to pass to this method.
+         *
+         * Skipping these steps means the permission callback may receive different input
+         * than it does during `execute()`, such as a missing schema default or a string
+         * instead of an integer.
          *
          * The checks run in this order:
@@ -769 +781 @@
          * @since 7.2.0 Added the `required_capabilities` check.
          *
-         * @see validate_input()
-         *
-         * @param mixed $input Optional. The valid input data for permission checking. Default `null`.
+         * @see WP_Ability::normalize_input()
+         * @see WP_Ability::validate_input()
+         * @see WP_Ability::coerce_input()
+         * @see WP_Ability::execute()
+         *
+         * @param mixed $input Optional. The normalized, validated, and coerced input data for permission checking.
+         *                     Default `null`.
          * @return bool|WP_Error Whether the ability has the necessary permission.
          */