Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
62 commits
Select commit Hold shift + click to select a range
99d4a74
Abilities API: Add a core/settings ability
jorgefilipecosta Jun 9, 2026
3765d5c
Abilities API: rename the core/settings 'slugs' input to 'settings'
jorgefilipecosta Jun 15, 2026
179917f
Abilities API: cover a custom registered setting in the core/settings…
jorgefilipecosta Jun 15, 2026
1361112
Abilities API: refine the core/settings ability per review.
jorgefilipecosta Jun 17, 2026
d65aaa0
Abilities API: use list<string> for the core/settings input schema do…
jorgefilipecosta Jun 19, 2026
40a3f0d
Abilities API: drop the unreachable recompute branch in execute_get_s…
jorgefilipecosta Jun 19, 2026
5d7940e
Abilities API: document the show_in_abilities registration-timing con…
jorgefilipecosta Jun 19, 2026
9f4726b
Abilities API: scope the WP_Settings_Abilities class.
jorgefilipecosta Jun 22, 2026
c5b4b62
Abilities API: make WP_Settings_Abilities instance-based.
jorgefilipecosta Jun 22, 2026
3390000
Update tests/phpunit/tests/abilities-api/wpRegisterCoreSettingsAbilit…
jorgefilipecosta Jul 2, 2026
46d6dd3
Abilities API: rename the core/settings ability to core/read-settings.
jorgefilipecosta Jul 2, 2026
2c12549
Abilities API: document why the settings abilities use a dedicated cl…
jorgefilipecosta Jul 2, 2026
b046fbf
Abilities API: serialize empty input schema defaults as objects.
jorgefilipecosta Jul 2, 2026
ae68b03
Abilities API: use ticket 64605 in the core/read-settings tests.
jorgefilipecosta Jul 2, 2026
8e7a6cd
Abilities API: register initial settings before core/read-settings sn…
jorgefilipecosta Jul 3, 2026
6f0039b
Abilities API: validate and sanitize core/read-settings values agains…
jorgefilipecosta Jul 7, 2026
1862471
Abilities API: Sync core/read-settings with the AI plugin
jorgefilipecosta Jul 10, 2026
5243336
Abilities API: Rename the core/read-settings ability to core/settings…
jorgefilipecosta Oct 6, 2026
d290c93
Abilities API: Preserve $new_allowed_options in core/settings-get.
jorgefilipecosta Oct 6, 2026
694db63
Abilities API: Update the core/settings-get @since tags to 7.2.0.
jorgefilipecosta Oct 6, 2026
e90de02
Abilities API: Update the PHPStan baseline for `show_in_abilities`.
jorgefilipecosta Oct 6, 2026
20e138f
Abilities API: Leave out core/settings-get values that fail their sch…
jorgefilipecosta Oct 6, 2026
a980c2f
Abilities API: Skip core/settings-get when no settings are exposed.
jorgefilipecosta Oct 6, 2026
0578e6f
Abilities API: Rename WP_Settings_Abilities to WP_Abilities_Settings.
jorgefilipecosta Oct 6, 2026
6af87b9
Abilities API: Serialize empty input schema defaults as objects.
jorgefilipecosta Oct 6, 2026
d3fad62
Abilities API: Refer to the planned core/settings-update ability.
jorgefilipecosta Oct 6, 2026
23f740f
Abilities API: Send empty object results as `{}` over REST.
jorgefilipecosta Oct 6, 2026
e61c6d7
Revert "Abilities API: Send empty object results as `{}` over REST."
jorgefilipecosta Oct 6, 2026
d09d8d7
Abilities API: Register the initial settings when abilities initialize.
jorgefilipecosta Oct 6, 2026
fab2c2c
Revert "Abilities API: Serialize empty input schema defaults as objec…
jorgefilipecosta Oct 6, 2026
27e9e4d
Abilities API: Read setting values as the settings endpoint does.
jorgefilipecosta Oct 6, 2026
e7704c9
Abilities API: Skip settings of an unsupported type in core/settings-…
jorgefilipecosta Oct 6, 2026
f1eb950
Abilities API: Expose the privacy policy page setting to abilities.
jorgefilipecosta Oct 6, 2026
ba8df3d
Abilities API: Simplify WP_Abilities_Settings.
jorgefilipecosta Oct 6, 2026
05de19a
Abilities API: Label the settings ability "Get Settings".
jorgefilipecosta Oct 6, 2026
dc2f496
Abilities API: Trim the `show_in_abilities` docs.
jorgefilipecosta Oct 6, 2026
783d9ea
Revert "Abilities API: Label the settings ability "Get Settings"."
jorgefilipecosta Oct 6, 2026
22b51eb
Abilities API: Default the `core/settings-get` input to an empty array.
jorgefilipecosta Oct 6, 2026
f82f2b0
Abilities API: Default the `core/settings-get` input to an empty object.
jorgefilipecosta Oct 6, 2026
1408795
Abilities API: Read a boolean setting stored as false as false.
jorgefilipecosta Oct 7, 2026
cb31b28
Abilities API: Reject undeclared object properties in setting values.
jorgefilipecosta Oct 7, 2026
b737712
Abilities API: Apply the `core/settings-get` filters to an object input.
jorgefilipecosta Oct 7, 2026
e34ddb6
Abilities API: Mark `core/settings-get` public and reuse REST setting…
gziolo Oct 7, 2026
d3a1e29
Abilities API: Use an empty array as the `core/settings-get` input de…
gziolo Oct 7, 2026
c16bf5f
Tests: Move the wp_prepare_json_schema_for_client() default tests to …
gziolo Oct 7, 2026
9ecd684
Tests: Restore the hooks right away in the `core/settings-get` tests.
jorgefilipecosta Oct 7, 2026
593f806
Abilities API: Apply the `core/settings-get` fields filter to a string.
jorgefilipecosta Oct 7, 2026
1465be9
Abilities API: Clarify that a `show_in_abilities` array replaces `sho…
jorgefilipecosta Oct 7, 2026
8924702
Tests: Check that `core/settings-get` skips settings only shown in REST.
jorgefilipecosta Oct 7, 2026
2f38556
Abilities API: Clarify that settings registered after abilities initi…
jorgefilipecosta Oct 7, 2026
68d95d9
Abilities API: Stop saying `core/settings-get` reads values as the se…
jorgefilipecosta Oct 7, 2026
ada469a
Abilities API: Match numeric setting names in `core/settings-get`.
jorgefilipecosta Oct 7, 2026
358659f
Abilities API: Leave out `core/settings-get` values that sanitizing i…
jorgefilipecosta Oct 7, 2026
9fafc9b
Tests: Refer to the site title as `title` in a `core/settings-get` test.
jorgefilipecosta Oct 8, 2026
6e377a1
Abilities API: Align the settings ability with the sibling abilities
jorgefilipecosta Oct 8, 2026
12fa8ef
Tests: Run the settings ability through the REST API
jorgefilipecosta Oct 8, 2026
b62e544
Abilities API: Keep the `core/settings-get` callbacks private.
jorgefilipecosta Oct 9, 2026
b7e4585
Abilities API: Describe how the `core/settings-get` filters combine.
jorgefilipecosta Oct 9, 2026
201b189
Abilities API: Describe `siteurl` as the WordPress installation URL.
jorgefilipecosta Oct 9, 2026
e817adf
Abilities API: Warn when two settings share a `core/settings-get` name.
jorgefilipecosta Oct 9, 2026
ed318f1
Abilities API: Leave out `core/settings-get` settings that were never…
jorgefilipecosta Oct 9, 2026
c597891
Tests: Update the REST API fixture for the new `siteurl` description.
jorgefilipecosta Oct 9, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions src/wp-includes/abilities.php
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@

declare( strict_types = 1 );

require_once __DIR__ . '/abilities/class-wp-abilities-settings.php';

/**
* Registers the core ability categories.
*
Expand Down Expand Up @@ -45,6 +47,7 @@ function wp_register_core_ability_categories(): void {
* Registers the default core abilities.
*
* @since 6.9.0
* @since 7.2.0 Added the `core/settings-get` ability.
*
* @global wpdb $wpdb WordPress database abstraction object.
*/
Expand Down Expand Up @@ -360,4 +363,7 @@ function wp_register_core_abilities(): void {
),
)
);

// Register the settings abilities (currently the read-only `core/settings-get`).
( new WP_Abilities_Settings() )->register();
}
340 changes: 340 additions & 0 deletions src/wp-includes/abilities/class-wp-abilities-settings.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,340 @@
<?php
/**
* Abilities API: WP_Abilities_Settings class.
*
* @package WordPress
* @subpackage Abilities API
* @since 7.2.0
*/

declare( strict_types = 1 );

/**
* Core class used to register settings-related abilities.
*
* Provides the read-only `core/settings-get` ability and the shared building blocks
* (exposed-settings discovery and schema generation) that are intended to also back a
* future write-oriented `core/settings-update` ability.
*
* Unlike the other core abilities, which are self-contained closures registered directly
* in wp_register_core_abilities(), the settings abilities live in a dedicated class
* because they share state: the set of exposed settings is computed once at registration
* and reused by the input schema, the output schema, and the execute callback, and the
* same helpers are meant to be shared with the future write ability.
*
* The exposed settings are captured when the ability registers, the first time the abilities
* registry is used in a request. Settings registered later in that request are not exposed.
* Core registers its own settings in time, see _wp_register_initial_settings_for_abilities().
*
* Only register() is public. The ability callbacks are closures that call private
* methods, so callers go through the Abilities API, such as
* `wp_get_ability( 'core/settings-get' )->execute()`, which validates the input and
* checks permissions before running them.
*
* @since 7.2.0
*
* @access private
*/
final class WP_Abilities_Settings {
Comment thread
jorgefilipecosta marked this conversation as resolved.
Resolved

/**
* The ability category used for settings abilities.
*
* @since 7.2.0
* @var string
*/
private const CATEGORY = 'site';

/**
* Settings exposed through the Abilities API, computed once at registration.
*
* @since 7.2.0
* @var array<string, array{option: string, group: string, default: mixed, schema: array<string, mixed>}>
*/
private $exposed_settings = array();

/**
* Registers all settings abilities.
*
* Must run on the `wp_abilities_api_init` hook. Registers nothing when no setting is
* exposed to abilities.
*
* @since 7.2.0
*/
public function register(): void {
$this->exposed_settings = $this->get_exposed_settings();
if ( empty( $this->exposed_settings ) ) {
return;
}

$this->register_settings_get();
}

/**
* Registers the read-only `core/settings-get` ability.
*
* @since 7.2.0
*/
private function register_settings_get(): void {
$groups = array_values( array_unique( array_filter( array_column( $this->exposed_settings, 'group' ) ) ) );

wp_register_ability(
'core/settings-get',
array(
'label' => __( 'Get Settings' ),
'description' => __( 'Returns WordPress settings as a flat map of setting name to value. By default returns all settings exposed to abilities, or optionally a subset filtered by settings group, by setting name, or both. A setting whose value does not match its schema is left out. Requires an authenticated user who can manage options.' ),
'category' => self::CATEGORY,
'input_schema' => $this->get_settings_get_input_schema( $groups, array_map( 'strval', array_keys( $this->exposed_settings ) ) ),
'output_schema' => $this->get_settings_get_output_schema(),
'execute_callback' => function ( $input = array() ): array {
return $this->execute_settings_get( $input );
},
'permission_callback' => function (): bool {
return $this->check_permission();
},
'meta' => array(
'annotations' => array(
'readonly' => true,
'destructive' => false,
'idempotent' => true,
),
'public' => true,
),
)
);
}

/**
* Executes the `core/settings-get` ability.
*
* @since 7.2.0
*
* @param mixed $input Optional. The ability input. Default empty array.
* @return array<string, mixed> Map of exposed setting name to current value.
*/
private function execute_settings_get( $input = array() ): array {
$input = rest_sanitize_object( $input );
$group = isset( $input['group'] ) && is_string( $input['group'] ) ? $input['group'] : '';
$fields = rest_sanitize_array( $input['fields'] ?? array() );

$result = array();
foreach ( $this->exposed_settings as $exposed_name => $setting ) {
if ( '' !== $group && $setting['group'] !== $group ) {
continue;
}
if ( ! empty( $fields ) && ! in_array( (string) $exposed_name, $fields, true ) ) {
continue;
}

/*
* As the settings endpoint does, read a setting that was never saved as its registered
* default, or leave it out when it has none: get_option() would return false, which a
* boolean schema accepts as a value and an array schema reads as an empty list.
*/
$value = get_option( $setting['option'], $setting['default'] );
if ( null === $value ) {
continue;
}

// WordPress stores false as '', which the boolean schema rejects.
Comment thread
jorgefilipecosta marked this conversation as resolved.
Resolved
if ( '' === $value && 'boolean' === $setting['schema']['type'] ) {
$value = false;
}

/*
* Leave out a value its schema rejects, before sanitizing (which could make it pass) or
* after (which could make it fail), instead of failing output validation for every setting.
*/
if ( is_wp_error( rest_validate_value_from_schema( $value, $setting['schema'] ) ) ) {
continue;
}

$value = rest_sanitize_value_from_schema( $value, $setting['schema'] );
if ( is_wp_error( rest_validate_value_from_schema( $value, $setting['schema'] ) ) ) {
continue;
}

// Object (not array()) so an empty object value is serialized as {}, consistent with type:object.
$result[ $exposed_name ] = 'object' === $setting['schema']['type'] ? (object) $value : $value;
}

return $result;
}

/**
* Permission callback for the settings abilities.
*
* The settings abilities read site options, so they are gated on the `manage_options`
* capability regardless of the input.
*
* @since 7.2.0
*
* @return bool True if the current user can manage options.
*/
private function check_permission(): bool {
return current_user_can( 'manage_options' );
}

/**
* Builds the input schema for the `core/settings-get` ability: optional filters by group and/or name.
*
* Both `group` and `fields` are optional; supplying both narrows the response to their
* intersection, and supplying neither returns every exposed setting.
*
* @since 7.2.0
*
* @param list<string> $groups Available settings groups.
* @param list<string> $field_names Available exposed setting names.
* @return array<string, mixed> The input JSON Schema.
*/
private function get_settings_get_input_schema( array $groups, array $field_names ): array {
return array(
'type' => 'object',
'default' => array(),
'properties' => array(
'group' => array(
'type' => 'string',
'enum' => $groups,
'description' => __( 'Return only settings that belong to this settings group. If omitted, settings of every group are returned.' ),
),
'fields' => array(
'type' => 'array',
'uniqueItems' => true,
'items' => array(
'type' => 'string',
'enum' => $field_names,
),
'description' => __( 'Return only the settings with these names. If omitted or empty, all settings allowed by the group filter are returned. When both filters are given, only settings matching both are returned.' ),
),
),
'additionalProperties' => false,
);
}

/**
* Builds the output schema for the `core/settings-get` ability.
*
* No setting is marked required because the `group` and `fields` inputs let the caller
* request any subset, and a setting whose value does not match its schema is left out.
*
* @since 7.2.0
*
* @return array<string, mixed> The output JSON Schema.
*/
private function get_settings_get_output_schema(): array {
return array(
'type' => 'object',
'description' => __( 'A map of setting name to its current value.' ),
'properties' => wp_list_pluck( $this->exposed_settings, 'schema' ),
'additionalProperties' => false,
);
}

/**
* Returns the settings exposed through the Abilities API.
*
* Reads {@see get_registered_settings()} and keeps only settings flagged with a truthy
* `show_in_abilities` argument, of a type the settings endpoint supports. Each entry is
* keyed by its exposed name and carries the underlying option name, the settings group,
* the registered default (null when there is none), and a JSON Schema describing the value.
*
* Two settings exposed under the same name trigger a notice, and the later one is exposed.
*
* @since 7.2.0
*
* @return array<string, array{option: string, group: string, default: mixed, schema: array<string, mixed>}> Settings keyed by exposed name.
*/
private function get_exposed_settings(): array {
$settings = array();

foreach ( get_registered_settings() as $option_name => $args ) {
if ( empty( $args['show_in_abilities'] ) ) {
continue;
}

$show = $this->get_exposure_args( $args );

$schema = $this->value_schema( $args, $show );
if ( ! in_array( $schema['type'], array( 'number', 'integer', 'string', 'boolean', 'array', 'object' ), true ) ) {
continue;
}

$option_name = (string) $option_name;
$exposed_name = empty( $show['name'] ) ? $option_name : (string) $show['name'];

if ( isset( $settings[ $exposed_name ] ) ) {
_doing_it_wrong(
__METHOD__,
sprintf(
/* translators: 1: Option name, 2: Setting name exposed to abilities, 3: Option name. */
__( 'The "%1$s" setting is exposed to abilities as "%2$s", a name already used by the "%3$s" setting, which is no longer exposed.' ),
esc_html( $option_name ),
esc_html( $exposed_name ),
esc_html( $settings[ $exposed_name ]['option'] )
),
'7.2.0'
);
}

$settings[ $exposed_name ] = array(
'option' => $option_name,
'group' => $args['group'] ?? '',
'default' => $args['default'] ?? null,
'schema' => $schema,
);
}

return $settings;
}

/**
* Returns the name and schema overrides used to expose a setting to abilities.
*
* When `show_in_abilities` is `true`, the setting is exposed the same way as in the
* REST API: it uses the `name` and `schema` from `show_in_rest`. An array is used
* as is.
*
* @since 7.2.0
*
* @param array<string, mixed> $args The setting registration arguments.
* @return array<string, mixed> The exposure arguments, with optional `name` and `schema` keys.
*/
private function get_exposure_args( array $args ): array {
if ( is_array( $args['show_in_abilities'] ) ) {
return $args['show_in_abilities'];
}

return is_array( $args['show_in_rest'] ) ? $args['show_in_rest'] : array();
}

/**
* Builds the JSON Schema describing a single setting's value.
*
* As in the settings endpoint, objects in the schema reject properties they do not declare,
* unless the schema allows them.
*
* @since 7.2.0
*
* @param array<string, mixed> $args The setting registration arguments.
* @param array<string, mixed> $show The exposure arguments, see get_exposure_args().
* @return array<string, mixed> The value JSON Schema.
*/
private function value_schema( array $args, $show ): array {
$schema = array(
'type' => $args['type'],
);
if ( ! empty( $args['label'] ) ) {
$schema['title'] = $args['label'];
}
if ( ! empty( $args['description'] ) ) {
$schema['description'] = $args['description'];
}
if ( isset( $show['schema'] ) && is_array( $show['schema'] ) ) {
/** @var array<string, mixed> $show_schema */
$show_schema = $show['schema'];
$schema = array_merge( $schema, $show_schema );
}

return rest_default_additional_properties_to_false( $schema );
}
}
1 change: 1 addition & 0 deletions src/wp-includes/default-filters.php
Original file line number Diff line number Diff line change
Expand Up @@ -556,6 +556,7 @@

// Abilities API.
add_action( 'wp_abilities_api_categories_init', 'wp_register_core_ability_categories' );
add_action( 'wp_abilities_api_init', '_wp_register_initial_settings_for_abilities', 1 );
add_action( 'wp_abilities_api_init', 'wp_register_core_abilities' );

// Connectors API.
Expand Down
Loading
Loading