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

Timestamp:

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