Skip to content

Commit d30bfa8

Browse files
committed
Abilities API: Replace coerce_input() with prepare_input()
Add a public `WP_Ability::prepare_input()` method that normalizes, validates, and sanitizes input in one call. Use it in `WP_Ability::execute()` and the REST run controller. Rename `coerce_input()` to the protected `sanitize_input()`, so sanitization cannot run on input that was not validated. `coerce_input()` was not released yet, so this is not a breaking change. Developed in #15685. Follow-up to [65044], [65306]. Props gziolo, jorgefilipecosta, justlevine, zaguiini. See #66383. Fixes #66482. git-svn-id: https://develop.svn.wordpress.org/trunk@65370 602fd350-edb4-49c9-b593-d223f7449a82
1 parent 49121d7 commit d30bfa8

5 files changed

Lines changed: 113 additions & 128 deletions

File tree

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

Lines changed: 20 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -200,10 +200,10 @@
200200
* #### Execute Callback
201201
*
202202
* The execute callback performs the ability's core functionality. It receives
203-
* the normalized, validated, and coerced input when an input schema is defined,
204-
* and no arguments otherwise. It returns either a result or `WP_Error` on failure.
205-
* Exceptions thrown by execute or permission callbacks are caught and converted
206-
* to a `WP_Error`.
203+
* the input prepared by `WP_Ability::prepare_input()` when an input schema is
204+
* defined, and no arguments otherwise. It returns either a result or `WP_Error`
205+
* on failure. Exceptions thrown by execute or permission callbacks are caught
206+
* and converted to a `WP_Error`.
207207
*
208208
* function my_plugin_analyze_text( string $input ): string|WP_Error {
209209
* $score = My_Plugin::perform_sentiment_analysis( $input );
@@ -228,10 +228,10 @@
228228
*
229229
* The permission callback determines whether the ability can be executed and
230230
* must return a boolean or `WP_Error`. When called through `WP_Ability::execute()`,
231-
* it receives the same normalized, validated, and coerced input as the execute
232-
* callback. Common use cases include checking user capabilities, validating API
233-
* keys, or verifying system state. In the example above, every execution requires
234-
* `edit_posts`, and the callback only adds the check that depends on the input:
231+
* it receives the same prepared input as the execute callback. Common use cases
232+
* include checking user capabilities, validating API keys, or verifying system
233+
* state. In the example above, every execution requires `edit_posts`, and the
234+
* callback only adds the check that depends on the input:
235235
*
236236
* function my_plugin_can_analyze_text( string $input ): bool|WP_Error {
237237
* // Only administrators can analyze long texts.
@@ -243,26 +243,24 @@
243243
*
244244
* ### Execution Lifecycle
245245
*
246-
* Call `WP_Ability::execute()` to normalize, validate, and coerce input, check
247-
* permissions, invoke the execute callback, and validate output. It returns the
248-
* result or a `WP_Error` on failure. Custom ability classes can override this
249-
* behavior.
246+
* Call `WP_Ability::execute()` to prepare the input, check permissions, invoke
247+
* the execute callback, and validate output. It returns the result or a
248+
* `WP_Error` on failure. Custom ability classes can override this behavior.
250249
*
251-
* Integrations that call `WP_Ability::check_permissions()` directly must prepare
252-
* the input first. See `WP_Ability::check_permissions()` for the required steps.
250+
* Integrations that call `WP_Ability::check_permissions()` directly must pass it
251+
* the input returned by `WP_Ability::prepare_input()`.
253252
*
254253
* Hooks run in this order, and processing stops at the first failure:
255254
*
256255
* 1. `wp_ability_invoked` action, with the raw input.
257256
* 2. `wp_pre_execute_ability` filter, which can short-circuit the rest of execution.
258-
* 3. `wp_ability_normalize_input`, `wp_ability_validate_input`, and
259-
* `wp_ability_permission_result` filters. The input validation filter runs only
260-
* when a non-empty input schema is defined. Input coercion has no filter. It runs
261-
* between validation and the permission check, only when a non-empty input
262-
* schema is defined.
263-
* 4. `wp_before_execute_ability` action.
264-
* 5. `wp_ability_execute_result` and `wp_ability_validate_output` filters.
265-
* 6. `wp_after_execute_ability` action.
257+
* 3. `wp_ability_normalize_input` and `wp_ability_validate_input` filters, while the
258+
* input is prepared. The input validation filter runs only when a non-empty input
259+
* schema is defined. Sanitization has no filter.
260+
* 4. `wp_ability_permission_result` filter.
261+
* 5. `wp_before_execute_ability` action.
262+
* 6. `wp_ability_execute_result` and `wp_ability_validate_output` filters.
263+
* 7. `wp_after_execute_ability` action.
266264
*
267265
* ### Client Exposure
268266
*

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

Lines changed: 56 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -563,34 +563,34 @@ public function normalize_input( $input = null ) {
563563
}
564564

565565
/**
566-
* Coerces validated input to the types declared in the input schema.
566+
* Sanitizes validated input against the input schema.
567567
*
568-
* Also applies schema format sanitization, such as stripping tags for
569-
* `text-field` and sanitizing URLs for `uri`, using `rest_sanitize_value_from_schema()`.
568+
* Converts values to the types declared in the input schema, and applies schema
569+
* format sanitization, such as stripping tags for `text-field` and sanitizing
570+
* URLs for `uri`, using `rest_sanitize_value_from_schema()`.
570571
*
571-
* Call `validate_input()` before this method. Coercing unvalidated input can
572-
* remove unknown properties or cast invalid values, hiding validation errors.
573-
* This method does not apply defaults or run input validation filters.
572+
* The input must be validated first. Sanitizing unvalidated input can remove
573+
* unknown properties or cast invalid values, hiding validation errors.
574574
*
575575
* If sanitization produces an error, including in a nested value, an invalid
576-
* input error is returned to prevent execution with uncoerced values.
576+
* input error is returned to prevent execution with unsanitized values.
577577
*
578578
* @since 7.2.0
579579
*
580-
* @see WP_Ability::validate_input()
580+
* @see WP_Ability::prepare_input()
581581
*
582582
* @param mixed $input Validated ability input.
583-
* @return mixed|WP_Error Coerced input, or `WP_Error` when it cannot be safely coerced.
583+
* @return mixed|WP_Error Sanitized input, or `WP_Error` when it cannot be safely sanitized.
584584
*/
585-
public function coerce_input( $input ) {
585+
protected function sanitize_input( $input ) {
586586
$schema = $this->get_input_schema();
587587
if ( null === $input || empty( $schema ) ) {
588588
return $input;
589589
}
590590

591591
$sanitized = rest_sanitize_value_from_schema( $input, $schema, 'input' );
592592

593-
// Values unique before coercion can collide after casting, even in nested arrays.
593+
// Values unique before sanitization can collide after casting, even in nested arrays.
594594
$error = self::get_input_error( $sanitized );
595595
if ( is_wp_error( $error ) ) {
596596
return new WP_Error(
@@ -698,6 +698,37 @@ public function validate_input( $input = null ) {
698698
return true;
699699
}
700700

701+
/**
702+
* Prepares input for the ability.
703+
*
704+
* Normalizes the input, validates it against the input schema, and then sanitizes
705+
* it. `execute()` passes the result to the permission and execute callbacks.
706+
* Validation runs before sanitization, so sanitization cannot make invalid input
707+
* valid.
708+
*
709+
* @since 7.2.0
710+
*
711+
* @see WP_Ability::normalize_input()
712+
* @see WP_Ability::validate_input()
713+
* @see WP_Ability::sanitize_input()
714+
*
715+
* @param mixed $input Optional. The raw input provided for the ability. Default `null`.
716+
* @return mixed|WP_Error The prepared input, or `WP_Error` when any step fails.
717+
*/
718+
public function prepare_input( $input = null ) {
719+
$input = $this->normalize_input( $input );
720+
if ( is_wp_error( $input ) ) {
721+
return $input;
722+
}
723+
724+
$is_valid = $this->validate_input( $input );
725+
if ( is_wp_error( $is_valid ) ) {
726+
return $is_valid;
727+
}
728+
729+
return $this->sanitize_input( $input );
730+
}
731+
701732
/**
702733
* Checks whether a value is a list of non-empty capability strings.
703734
*
@@ -754,17 +785,10 @@ protected function invoke_callback( callable $callback, $input = null ) {
754785
* This method does not prepare the input. Use `execute()` to run the full ability
755786
* lifecycle, which prepares the input before calling this method.
756787
*
757-
* When calling this method directly, prepare the input in the same order as
758-
* `execute()`, and stop if any step returns a `WP_Error`:
759-
*
760-
* 1. `normalize_input()` applies the schema default and returns the input.
761-
* 2. `validate_input()` checks the input against the schema and returns `true`.
762-
* 3. `coerce_input()` converts values to the schema types and returns the input
763-
* to pass to this method.
764-
*
765-
* Skipping these steps means the permission callback may receive different input
766-
* than it does during `execute()`, such as a missing schema default or a string
767-
* instead of an integer.
788+
* When calling this method directly, pass the input returned by `prepare_input()`,
789+
* and stop if it returns a `WP_Error`. Skipping this step means the permission
790+
* callback may receive different input than it does during `execute()`, such as
791+
* a missing schema default or a string instead of an integer.
768792
*
769793
* The checks run in this order:
770794
*
@@ -780,12 +804,10 @@ protected function invoke_callback( callable $callback, $input = null ) {
780804
* @since 7.1.0 Added the `wp_ability_permission_result` filter.
781805
* @since 7.2.0 Added the `required_capabilities` check.
782806
*
783-
* @see WP_Ability::normalize_input()
784-
* @see WP_Ability::validate_input()
785-
* @see WP_Ability::coerce_input()
807+
* @see WP_Ability::prepare_input()
786808
* @see WP_Ability::execute()
787809
*
788-
* @param mixed $input Optional. The normalized, validated, and coerced input data for permission checking.
810+
* @param mixed $input Optional. The input prepared by `prepare_input()` for permission checking.
789811
* Default `null`.
790812
* @return bool|WP_Error Whether the ability has the necessary permission.
791813
*/
@@ -884,7 +906,7 @@ protected function do_execute( $input = null ) {
884906
* @param mixed $result The result returned by the registered `execute_callback`,
885907
* or a `WP_Error` if execution failed.
886908
* @param string $ability_name The name of the ability.
887-
* @param mixed $input The normalized input data.
909+
* @param mixed $input The prepared input data.
888910
* @param WP_Ability $ability The ability instance.
889911
*/
890912
return apply_filters( 'wp_ability_execute_result', $result, $this->name, $input, $this );
@@ -946,13 +968,13 @@ protected function validate_output( $output ) {
946968
}
947969

948970
/**
949-
* Executes the ability after input validation, coercion, and a permission check.
971+
* Executes the ability after preparing the input and checking permissions.
950972
* Before returning the return value, it also validates the output.
951973
*
952974
* @since 6.9.0
953975
* @since 7.1.0 Added the `wp_ability_invoked` action.
954976
* @since 7.1.0 Added the `wp_pre_execute_ability` filter.
955-
* @since 7.2.0 Coerces validated input before permission checks and execution.
977+
* @since 7.2.0 Prepares the input with `prepare_input()`, which also sanitizes it.
956978
*
957979
* @param mixed $input Optional. The input data for the ability. Default `null`.
958980
* @return mixed|WP_Error The result of the ability execution, or WP_Error on failure.
@@ -979,7 +1001,7 @@ public function execute( $input = null ) {
9791001
* Filters whether to short-circuit ability execution.
9801002
*
9811003
* Returning a value other than the received default bypasses the rest of `execute()` —
982-
* input normalization, input validation, permission checks, the registered execute callback,
1004+
* input preparation, permission checks, the registered execute callback,
9831005
* output validation, and the surrounding actions — and the value is returned to the caller
9841006
* as-is. Useful for cached responses, rate limiting, maintenance mode, and test mocking.
9851007
*
@@ -1002,17 +1024,7 @@ public function execute( $input = null ) {
10021024
return $pre;
10031025
}
10041026

1005-
$input = $this->normalize_input( $input );
1006-
if ( is_wp_error( $input ) ) {
1007-
return $input;
1008-
}
1009-
1010-
$is_valid = $this->validate_input( $input );
1011-
if ( is_wp_error( $is_valid ) ) {
1012-
return $is_valid;
1013-
}
1014-
1015-
$input = $this->coerce_input( $input );
1027+
$input = $this->prepare_input( $input );
10161028
if ( is_wp_error( $input ) ) {
10171029
return $input;
10181030
}
@@ -1036,13 +1048,13 @@ public function execute( $input = null ) {
10361048
}
10371049

10381050
/**
1039-
* Fires before an ability gets executed, after input validation and permissions check.
1051+
* Fires before an ability gets executed, after input preparation and permissions check.
10401052
*
10411053
* @since 6.9.0
10421054
* @since 7.1.0 Added the `$ability` parameter.
10431055
*
10441056
* @param string $ability_name The name of the ability.
1045-
* @param mixed $input The validated and coerced input data for the ability.
1057+
* @param mixed $input The prepared input data for the ability.
10461058
* @param WP_Ability $ability The ability instance.
10471059
*/
10481060
do_action( 'wp_before_execute_ability', $this->name, $input, $this );
@@ -1064,7 +1076,7 @@ public function execute( $input = null ) {
10641076
* @since 7.1.0 Added the `$ability` parameter.
10651077
*
10661078
* @param string $ability_name The name of the ability.
1067-
* @param mixed $input The validated and coerced input data for the ability.
1079+
* @param mixed $input The prepared input data for the ability.
10681080
* @param mixed $result The result of the ability execution.
10691081
* @param WP_Ability $ability The ability instance.
10701082
*/

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

Lines changed: 1 addition & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -172,7 +172,7 @@ public function check_ability_permissions( $request ) {
172172
return $is_valid;
173173
}
174174

175-
$input = $this->prepare_input_for_ability( $ability, $this->get_input_from_request( $request ) );
175+
$input = $ability->prepare_input( $this->get_input_from_request( $request ) );
176176
if ( is_wp_error( $input ) ) {
177177
return $this->ensure_error_status( $input, 400 );
178178
}
@@ -249,30 +249,6 @@ public function sanitize_input_for_ability( $input, $request ) {
249249
return $input;
250250
}
251251

252-
/**
253-
* Normalizes, validates, and coerces input for an ability.
254-
*
255-
* @since 7.2.0
256-
*
257-
* @param WP_Ability $ability The ability to prepare input for.
258-
* @param mixed $input Input to prepare.
259-
* @return mixed|WP_Error Prepared input, or `WP_Error` when normalization, validation, or coercion fails.
260-
*/
261-
private function prepare_input_for_ability( WP_Ability $ability, $input ) {
262-
$input = $ability->normalize_input( $input );
263-
if ( is_wp_error( $input ) ) {
264-
return $input;
265-
}
266-
267-
// Validate before coercion so sanitization cannot rescue invalid input.
268-
$is_valid = $ability->validate_input( $input );
269-
if ( is_wp_error( $is_valid ) ) {
270-
return $is_valid;
271-
}
272-
273-
return $ability->coerce_input( $input );
274-
}
275-
276252
/**
277253
* Retrieves the arguments for ability execution endpoint.
278254
*

0 commit comments

Comments
 (0)