Skip to content

Commit eece764

Browse files
committed
Abilities API: Add WP_Ability::prepare_input().
Adds `WP_Ability::prepare_input()`, which normalizes, validates, and sanitizes the input in one call. `execute()` and the REST run controller now use it, so they no longer repeat the three steps. Integrations that call `check_permissions()` directly can also use it. `coerce_input()` is renamed to the protected `sanitize_input()`. It must only run on validated input, so `prepare_input()` is now the public way to reach it. `coerce_input()` was added in 7.2 and has not been released yet. The documentation now refers to `prepare_input()` instead of listing each step. Tests about the sanitization step use "sanitization" in their names. See #66383.
1 parent c636204 commit eece764

5 files changed

Lines changed: 110 additions & 125 deletions

File tree

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

Lines changed: 19 additions & 21 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
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
262259
* 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.
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: 54 additions & 42 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.
@@ -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
}
@@ -1042,7 +1054,7 @@ public function execute( $input = null ) {
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
*

‎tests/phpunit/tests/abilities-api/wpAbility.php‎

Lines changed: 16 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -2336,24 +2336,22 @@ public static function data_input_is_coerced(): array {
23362336
}
23372337

23382338
/**
2339-
* Tests that validated input is coerced to the ability input schema.
2339+
* Tests that `prepare_input()` sanitizes input to the ability input schema.
23402340
*
23412341
* @ticket 65594
23422342
*
23432343
* @dataProvider data_input_is_coerced
23442344
*
23452345
* @param array $schema Ability input schema.
23462346
* @param mixed $input Raw ability input.
2347-
* @param mixed $expected Expected input value after coercion.
2347+
* @param mixed $expected Expected input value after preparation.
23482348
*/
2349-
public function test_input_is_coerced( array $schema, $input, $expected ): void {
2349+
public function test_prepare_input( array $schema, $input, $expected ): void {
23502350
$args = self::$test_ability_properties;
23512351
$args['input_schema'] = $schema;
23522352
$ability = new WP_Ability( self::$test_ability_name, $args );
2353-
$input = $ability->normalize_input( $input );
23542353

2355-
$this->assertTrue( $ability->validate_input( $input ) );
2356-
$this->assertSame( $expected, $ability->coerce_input( $input ) );
2354+
$this->assertSame( $expected, $ability->prepare_input( $input ) );
23572355
}
23582356

23592357
/**
@@ -2429,11 +2427,11 @@ static function ( $name, $value ) use ( &$seen ) {
24292427
}
24302428

24312429
/**
2432-
* Provides top-level and nested collisions introduced by coercion.
2430+
* Provides top-level and nested collisions introduced by sanitization.
24332431
*
24342432
* @return array
24352433
*/
2436-
public static function data_input_coercion_errors(): array {
2434+
public static function data_input_sanitization_errors(): array {
24372435
$unique = array(
24382436
'type' => 'array',
24392437
'items' => array( 'type' => 'integer' ),
@@ -2466,20 +2464,20 @@ public static function data_input_coercion_errors(): array {
24662464
}
24672465

24682466
/**
2469-
* Tests that coercion errors stop permission checks, execution, and execution hooks.
2467+
* Tests that sanitization errors stop permission checks, execution, and execution hooks.
24702468
*
24712469
* @ticket 66383
2472-
* @dataProvider data_input_coercion_errors
2470+
* @dataProvider data_input_sanitization_errors
24732471
*
24742472
* @param array $schema Input schema.
2475-
* @param mixed $input Input accepted by validation but rejected by coercion.
2473+
* @param mixed $input Input accepted by validation but rejected by sanitization.
24762474
* @param string $path Path of the duplicate items in the error message.
24772475
*/
2478-
public function test_input_coercion_errors( array $schema, $input, string $path ): void {
2476+
public function test_input_sanitization_errors( array $schema, $input, string $path ): void {
24792477
$args = self::$test_ability_properties;
24802478
$args['input_schema'] = $schema;
24812479
$unexpected_callback = function () {
2482-
$this->fail( 'Coercion errors must stop permission checks and execution.' );
2480+
$this->fail( 'Sanitization errors must stop permission checks and execution.' );
24832481
};
24842482

24852483
$args['permission_callback'] = $unexpected_callback;
@@ -2489,21 +2487,21 @@ public function test_input_coercion_errors( array $schema, $input, string $path
24892487
add_action( 'wp_before_execute_ability', $unexpected_callback );
24902488
add_action( 'wp_after_execute_ability', $unexpected_callback );
24912489

2492-
$this->assertTrue( $ability->validate_input( $input ), 'The error should arise during coercion.' );
2493-
$error = $ability->coerce_input( $input );
2490+
$this->assertTrue( $ability->validate_input( $input ), 'The error should arise during sanitization.' );
2491+
$error = $ability->prepare_input( $input );
24942492
$this->assertWPError( $error );
24952493
$this->assertSame( 'ability_invalid_input', $error->get_error_code() );
24962494
$this->assertStringContainsString( $path . ' has duplicate items.', $error->get_error_message() );
24972495
// Keep assertEquals() because the objects are intentionally compared by value.
2498-
$this->assertEquals( $error, $ability->execute( $input ), 'Execution should propagate the coercion error.' );
2496+
$this->assertEquals( $error, $ability->execute( $input ), 'Execution should propagate the sanitization error.' );
24992497
}
25002498

25012499
/**
2502-
* Tests that coercion cannot rescue invalid input or bypass validation filters.
2500+
* Tests that sanitization cannot rescue invalid input or bypass validation filters.
25032501
*
25042502
* @ticket 66383
25052503
*/
2506-
public function test_coercion_respects_input_validation(): void {
2504+
public function test_sanitization_respects_input_validation(): void {
25072505
$seen = array();
25082506
$args = self::$test_ability_properties;
25092507
$args['input_schema'] = array(

0 commit comments

Comments
 (0)