Changeset 62426 for trunk/src/wp-includes/abilities.php

Timestamp:

05/28/2026 07:46:15 AM (3 months ago)

Author:

gziolo

Message:

Abilities API: Unify schema conventions across core abilities

Align core/get-site-info, core/get-user-info, and core/get-environment-info on a shared blueprint: every output property carries a Title Case title and a description, core/get-environment-info gains the optional fields input parameter the other two already accept, and core/get-user-info is exposed via REST. Descriptions are also tightened for programmatic consumers, and registration tests now lock the exact ordered set of property keys.

Props gziolo, westonruter.
Fixes #65355.

File:

• trunk/src/wp-includes/abilities.php (modified) (5 diffs)

trunk/src/wp-includes/abilities.php

@@ -47 +47 @@
                 'name'        => array(
                         'type'        => 'string',
+                        'title'       => __( 'Site Title' ),
                         'description' => __( 'The site title.' ),
                 ),
                 'description' => array(
                         'type'        => 'string',
+                        'title'       => __( 'Tagline' ),
                         'description' => __( 'The site tagline.' ),
                 ),
                 'url'         => array(
                         'type'        => 'string',
-                        'description' => __( 'The site home URL.' ),
+                        'title'       => __( 'Site Address (URL)' ),
+                        'description' => __( 'The public URL where visitors access the site. May differ from the WordPress installation URL.' ),
                 ),
                 'wpurl'       => array(
                         'type'        => 'string',
-                        'description' => __( 'The WordPress installation URL.' ),
+                        'title'       => __( 'WordPress Address (URL)' ),
+                        'description' => __( 'The URL where WordPress core files are served. May differ from the public site URL.' ),
                 ),
                 'admin_email' => array(
                         'type'        => 'string',
+                        'title'       => __( 'Administration Email Address' ),
                         'description' => __( 'The site administrator email address.' ),
                 ),
                 'charset'     => array(
                         'type'        => 'string',
+                        'title'       => __( 'Site Charset' ),
                         'description' => __( 'The site character encoding.' ),
                 ),
                 'language'    => array(
                         'type'        => 'string',
-                        'description' => __( 'The site language locale code.' ),
+                        'title'       => __( 'Site Language' ),
+                        'description' => __( 'The site locale in dash form (e.g. en-US).' ),
                 ),
                 'version'     => array(
                         'type'        => 'string',
-                        'description' => __( 'The WordPress version.' ),
+                        'title'       => __( 'WordPress Version' ),
+                        'description' => __( 'The WordPress core version running on this site.' ),
                 ),
         );
@@ -139 +147 @@
                         'type'        => 'integer',
                         'title'       => __( 'User ID' ),
-                        'description' => __( 'Unique numeric identifier for the user.' ),
+                        'description' => __( 'Unique identifier for the user.' ),
                 ),
                 'display_name'  => array(
@@ -187 +195 @@
                         'type'        => 'string',
                         'title'       => __( 'Biographical Info' ),
-                        'description' => __( 'User-authored biography, often shown on author pages.' ),
+                        'description' => __( 'User-authored biography. May be empty.' ),
                 ),
                 'user_url'      => array(
@@ -254 +262 @@
                                         'idempotent'  => true,
                                 ),
-                                'show_in_rest' => false,
-                        ),
-                )
-        );
+                                'show_in_rest' => true,
+                        ),
+                )
+        );
+
+        $environment_info_properties = array(
+                'environment'    => array(
+                        'type'        => 'string',
+                        'title'       => __( 'Environment Type' ),
+                        'description' => __( 'The site\'s runtime environment classification.' ),
+                        'enum'        => array( 'production', 'staging', 'development', 'local' ),
+                ),
+                'php_version'    => array(
+                        'type'        => 'string',
+                        'title'       => __( 'PHP Version' ),
+                        'description' => __( 'The PHP runtime version executing WordPress.' ),
+                ),
+                'db_server_info' => array(
+                        'type'        => 'string',
+                        'title'       => __( 'Database Server Info' ),
+                        'description' => __( 'The database server vendor and version string reported by the driver.' ),
+                ),
+                'wp_version'     => array(
+                        'type'        => 'string',
+                        'title'       => __( 'WordPress Version' ),
+                        'description' => __( 'The WordPress core version running on this site.' ),
+                ),
+        );
+        $environment_info_fields     = array_keys( $environment_info_properties );
 
         wp_register_ability(
@@ -263 +296 @@
                 array(
                         'label'               => __( 'Get Environment Info' ),
-                        'description'         => __( 'Returns core details about the site\'s runtime context for diagnostics and compatibility (environment, PHP runtime, database server info, WordPress version).' ),
+                        'description'         => __( 'Returns core details about the site\'s runtime context for diagnostics and compatibility (environment, PHP runtime, database server info, WordPress version). By default returns all fields, or optionally a filtered subset.' ),
                         'category'            => $category_site,
+                        'input_schema'        => array(
+                                'type'                 => 'object',
+                                'properties'           => array(
+                                        'fields' => array(
+                                                'type'        => 'array',
+                                                'items'       => array(
+                                                        'type' => 'string',
+                                                        'enum' => $environment_info_fields,
+                                                ),
+                                                'description' => __( 'Optional: Limit response to specific fields. If omitted, all fields are returned.' ),
+                                        ),
+                                ),
+                                'additionalProperties' => false,
+                                'default'              => array(),
+                        ),
                         'output_schema'       => array(
                                 'type'                 => 'object',
-                                'required'             => array( 'environment', 'php_version', 'db_server_info', 'wp_version' ),
-                                'properties'           => array(
-                                        'environment'    => array(
-                                                'type'        => 'string',
-                                                'description' => __( 'The site\'s runtime environment classification (can be one of these: production, staging, development, local).' ),
-                                                'enum'        => array( 'production', 'staging', 'development', 'local' ),
-                                        ),
-                                        'php_version'    => array(
-                                                'type'        => 'string',
-                                                'description' => __( 'The PHP runtime version executing WordPress.' ),
-                                        ),
-                                        'db_server_info' => array(
-                                                'type'        => 'string',
-                                                'description' => __( 'The database server vendor and version string reported by the driver.' ),
-                                        ),
-                                        'wp_version'     => array(
-                                                'type'        => 'string',
-                                                'description' => __( 'The WordPress core version running on this site.' ),
-                                        ),
-                                ),
-                                'additionalProperties' => false,
-                        ),
-                        'execute_callback'    => static function (): array {
+                                'properties'           => $environment_info_properties,
+                                'additionalProperties' => false,
+                        ),
+                        'execute_callback'    => static function ( $input = array() ) use ( $environment_info_fields ): array {
                                 global $wpdb;
 
-                                $env          = wp_get_environment_type();
-                                $php_version  = phpversion();
-                                $db_server_info  = '';
+                                /** @var array{ fields?: string[] } $input */
+                                $input            = is_array( $input ) ? $input : array();
+                                $requested_fields = ! empty( $input['fields'] ) ? $input['fields'] : $environment_info_fields;
+
+                                $db_server_info = '';
                                 if ( method_exists( $wpdb, 'db_server_info' ) ) {
                                         $db_server_info = $wpdb->db_server_info() ?? '';
                                 }
-                                $wp_version   = get_bloginfo( 'version' );
-
-                                return array(
-                                        'environment'    => $env,
-                                        'php_version'    => $php_version,
+
+                                $all = array(
+                                        'environment'    => wp_get_environment_type(),
+                                        'php_version'    => phpversion(),
                                         'db_server_info' => $db_server_info,
-                                        'wp_version'     => $wp_version,
+                                        'wp_version'     => get_bloginfo( 'version' ),
                                 );
+
+                                return array_intersect_key( $all, array_flip( $requested_fields ) );
                         },
                         'permission_callback' => static function (): bool {