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

Timestamp:

11/06/2026 08:36:45 AM (7 hours 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.

File:

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

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.
          */