Changeset 61047

Timestamp:

10/22/2025 03:02:29 PM (3 months ago)

Author:

gziolo

Message:

Abilities API: Normalize input from schema

Without this patch REST API would require a weird empty ?input field for optional input given how the current controller works with input schema when it defines the expected shape. This patch normalizes the input for the ability, applying the default value from the input schema when needed.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10395.

Follow-up [61032], [61045].

Props gziolo, jorgefilipecosta, mukesh27.
Fixes #64139.

Location:

trunk

Files:

• src/wp-includes/abilities-api/class-wp-ability.php (modified) (2 diffs)
• src/wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-categories-controller.php (modified) (1 diff)
• src/wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-list-controller.php (modified) (1 diff)
• src/wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-run-controller.php (modified) (1 diff)
• tests/phpunit/tests/rest-api/wpRestAbilitiesV1RunController.php (modified) (3 diffs)

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

@@ -402 +402 @@
 
     /**
+     * Normalizes the input for the ability, applying the default value from the input schema when needed.
+     *
+     * When no input is provided and the input schema is defined with a top-level `default` key, this method returns
+     * the value of that key. If the input schema does not define a `default`, or if the input schema is empty,
+     * this method returns null. If input is provided, it is returned as-is.
+     *
+     * @since 6.9.0
+     *
+     * @param mixed $input Optional. The raw input provided for the ability. Default `null`.
+     * @return mixed The same input, or the default from schema, or `null` if default not set.
+     */
+    public function normalize_input( $input = null ) {
+        if ( null !== $input ) {
+            return $input;
+        }
+
+        $input_schema = $this->get_input_schema();
+        if ( ! empty( $input_schema ) && array_key_exists( 'default', $input_schema ) ) {
+            return $input_schema['default'];
+        }
+
+        return null;
+    }
+
+    /**
      * Validates input data against the input schema.
      *
@@ -537 +562 @@
      */
     public function execute( $input = null ) {
+        $input    = $this->normalize_input( $input );
         $is_valid = $this->validate_input( $input );
         if ( is_wp_error( $is_valid ) ) {

trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-categories-controller.php

@@ -94 +94 @@
 
         $total_categories = count( $categories );
-        $max_pages        = ceil( $total_categories / $per_page );
+        $max_pages        = (int) ceil( $total_categories / $per_page );
 
         if ( $request->get_method() === 'HEAD' ) {

trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-list-controller.php

@@ -112 +112 @@
 
         $total_abilities = count( $abilities );
-        $max_pages       = ceil( $total_abilities / $per_page );
+        $max_pages       = (int) ceil( $total_abilities / $per_page );
 
         if ( $request->get_method() === 'HEAD' ) {

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

@@ -160 +160 @@
 
         $input    = $this->get_input_from_request( $request );
+        $input    = $ability->normalize_input( $input );
         $is_valid = $ability->validate_input( $input );
         if ( is_wp_error( $is_valid ) ) {

trunk/tests/phpunit/tests/rest-api/wpRestAbilitiesV1RunController.php

@@ -922 +922 @@
 
     /**
-     * Test edge case with empty input for both GET and POST methods.
-     *
-     * @ticket 64098
-     */
-    public function test_empty_input_handling(): void {
-        // Registers abilities for empty input testing.
+     * Test edge case with empty input for GET method.
+     *
+     * @ticket 64098
+     */
+    public function test_empty_input_handling_get_method(): void {
         wp_register_ability(
             'test/read-only-empty',
@@ -942 +941 @@
                         'readonly' => true,
                     ),
-                    'show_in_rest' => true,
-                ),
-            )
-        );
-
-        wp_register_ability(
-            'test/regular-empty',
-            array(
-                'label'               => 'Regular Empty',
-                'description'         => 'Regular with empty input.',
-                'category'            => 'general',
-                'execute_callback'    => static function () {
-                    return array( 'input_was_empty' => 0 === func_num_args() );
-                },
-                'permission_callback' => '__return_true',
-                'meta'                => array(
                     'show_in_rest' => true,
                 ),
@@ -968 +951 @@
         $this->assertEquals( 200, $get_response->get_status() );
         $this->assertTrue( $get_response->get_data()['input_was_empty'] );
+    }
+
+    /**
+     * Test edge case with empty input for GET method, and normalized input using schema.
+     *
+     * @ticket 64098
+     */
+    public function test_empty_input_handling_get_method_with_normalized_input(): void {
+        wp_register_ability(
+            'test/read-only-empty-array',
+            array(
+                'label'               => 'Read-only Empty Array',
+                'description'         => 'Read-only with inferred empty array input from schema.',
+                'category'            => 'general',
+                'input_schema'        => array(
+                    'type'    => 'array',
+                    'default' => array(),
+                ),
+                'execute_callback'    => static function ( $input ) {
+                    return is_array( $input ) && empty( $input );
+                },
+                'permission_callback' => '__return_true',
+                'meta'                => array(
+                    'annotations'  => array(
+                        'readonly' => true,
+                    ),
+                    'show_in_rest' => true,
+                ),
+            )
+        );
+
+        // Tests GET with no input parameter.
+        $get_request  = new WP_REST_Request( 'GET', '/wp-abilities/v1/abilities/test/read-only-empty-array/run' );
+        $get_response = $this->server->dispatch( $get_request );
+        $this->assertEquals( 200, $get_response->get_status() );
+        $this->assertTrue( $get_response->get_data() );
+    }
+
+    /**
+     * Test edge case with empty input for POST method.
+     *
+     * @ticket 64098
+     */
+    public function test_empty_input_handling_post_method(): void {
+        wp_register_ability(
+            'test/regular-empty',
+            array(
+                'label'               => 'Regular Empty',
+                'description'         => 'Regular with empty input.',
+                'category'            => 'general',
+                'execute_callback'    => static function () {
+                    return array( 'input_was_empty' => 0 === func_num_args() );
+                },
+                'permission_callback' => '__return_true',
+                'meta'                => array(
+                    'show_in_rest' => true,
+                ),
+            )
+        );
 
         // Tests POST with no body.