@@ -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 */
0 commit comments