Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
3 changes: 2 additions & 1 deletion src/wp-includes/abilities.php
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@ function wp_register_core_ability_categories(): void {
*
* @since 6.9.0
* @since 7.2.0 Added the `core/content-query`, `core/settings-get`, and `core/users-query` abilities.
* @since 7.3.0 Added the `core/settings-update` ability.
*
* @global wpdb $wpdb WordPress database abstraction object.
*/
Expand Down Expand Up @@ -371,7 +372,7 @@ function wp_register_core_abilities(): void {
)
);

// Register the settings abilities (currently the read-only `core/settings-get`).
// Register the settings abilities (get and update).
( new WP_Abilities_Settings() )->register();

// Register the user abilities (currently the read-only `core/users-query`).
Expand Down
258 changes: 238 additions & 20 deletions src/wp-includes/abilities/class-wp-abilities-settings.php
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,14 @@
/**
* 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.
* Provides the `core/settings-get` and `core/settings-update` abilities and the building
* blocks they share (exposed-settings discovery, schema generation and reading the values).
*
* Unlike the core abilities registered directly in wp_register_core_abilities() as
* self-contained closures, 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.
* and reused by the input schemas, the output schemas, and the execute callbacks of both
* abilities.
*
* 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.
Expand All @@ -32,6 +31,7 @@
* checks permissions before running them.
*
* @since 7.2.0
* @since 7.3.0 Added the `core/settings-update` ability.
*
* @access private
*/
Expand All @@ -51,7 +51,15 @@ final class WP_Abilities_Settings {
* @since 7.2.0
* @var array<string, array{option: string, group: string, default: mixed, schema: array<string, mixed>}>
*/
private $exposed_settings = array();
private array $exposed_settings = array();

/**
* Exposed settings that `core/settings-update` can write, computed once at registration.
*
* @since 7.3.0
* @var array<string, array{option: string, group: string, default: mixed, schema: array<string, mixed>}>
*/
private array $writable_settings = array();

/**
* Registers all settings abilities.
Expand All @@ -60,14 +68,25 @@ final class WP_Abilities_Settings {
* exposed to abilities.
*
* @since 7.2.0
* @since 7.3.0 Registers the `core/settings-update` ability.
*/
public function register(): void {
$this->exposed_settings = $this->get_exposed_settings();
if ( empty( $this->exposed_settings ) ) {
return;
}

/*
* Intentionally strict: a setting whose schema is read-only cannot be updated, so naming
* it is refused like any unknown name.
*/
$this->writable_settings = array_filter(
$this->exposed_settings,
static fn( array $setting ): bool => empty( $setting['schema']['readonly'] )
);

$this->register_settings_get();
$this->register_settings_update();
}

/**
Expand All @@ -85,7 +104,7 @@ private function register_settings_get(): void {
'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(),
'output_schema' => $this->get_settings_output_schema( __( 'A map of setting name to its current value.' ) ),
'execute_callback' => function ( $input = array() ): array {
return $this->execute_settings_get( $input );
},
Expand All @@ -102,6 +121,119 @@ private function register_settings_get(): void {
);
}

/**
* Registers the `core/settings-update` ability.
*
* Registers nothing when no exposed setting is writable.
*
* @since 7.3.0
*/
private function register_settings_update(): void {
if ( empty( $this->writable_settings ) ) {
return;
}

wp_register_ability(
'core/settings-update',
array(
'label' => __( 'Update Settings' ),
'description' => __( 'Updates WordPress settings and returns the saved values of the settings named in the call. A null value deletes the stored value of a setting, which then reads as its default when it has one. Requires an authenticated user who can manage options.' ),
'category' => self::CATEGORY,
'input_schema' => $this->get_settings_update_input_schema(),
'output_schema' => $this->get_settings_output_schema( __( 'A map of setting name to its value after the update.' ) ),
'execute_callback' => function ( $input ) {
return $this->execute_settings_update( $input );
},
'required_capabilities' => array( 'manage_options' ),
'meta' => array(
'annotations' => array(
'readonly' => false,
'destructive' => false,
'idempotent' => true,
),
'public' => true,
),
)
);
}

/**
* Executes the `core/settings-update` ability.
*
* Every check runs before the first write, so a call that ends in an error changes nothing.
* The output holds only the settings named in the call, read the same way as for
* `core/settings-get`.
*
* @since 7.3.0
*
* @param array{data: array<string, mixed>} $input The ability input, as prepared by WP_Ability::execute().
* @return array<string, mixed>|WP_Error Map of the named setting names to their values after the update,
* or an error when the update is refused.
*/
private function execute_settings_update( array $input ) {
// A permission filter can grant the call to a user who cannot manage options, who must still not write.
if ( ! current_user_can( 'manage_options' ) ) {
return new WP_Error(
'settings_cannot_update',
__( 'Sorry, you are not allowed to manage options for this site.' ),
array( 'status' => rest_authorization_required_code() )
);
}

$data = $input['data'];
$named = array_intersect_key( $this->writable_settings, $data );

// A setting unregistered since the abilities initialized is neither checked, written nor returned.
$registered = get_registered_settings();
$named = array_filter(
$named,
static fn( array $setting ): bool => isset( $registered[ $setting['option'] ] )
);

/*
* Intentionally strict: the whole call is refused, instead of leaving this one setting out
* of the update. The rule belongs to the option, whatever name exposes it.
*/
if ( in_array( 'wp_page_for_privacy_policy', array_column( $named, 'option' ), true ) && ! current_user_can( 'manage_privacy_options' ) ) {
return new WP_Error(
'settings_cannot_manage_privacy_options',
__( 'Sorry, you are not allowed to manage privacy options on this site.' ),
array( 'status' => rest_authorization_required_code() )
);
}

/*
* Intentionally strict: every null value is checked before the first write, so a refused
* call changes nothing. A null value is refused while the stored value does not match the
* setting's schema.
*/
foreach ( $named as $exposed_name => $setting ) {
if ( null !== $data[ $exposed_name ] ) {
continue;
}

if ( is_wp_error( rest_validate_value_from_schema( $this->get_stored_value( $setting, false ), $setting['schema'] ) ) ) {
return new WP_Error(
'settings_invalid_stored_value',
/* translators: %s: Property name. */
sprintf( __( 'The %s property has an invalid stored value, and cannot be updated to null.' ), $exposed_name ),
array( 'status' => 500 )
);
}
}

foreach ( $named as $exposed_name => $setting ) {
if ( null === $data[ $exposed_name ] ) {
delete_option( $setting['option'] );
continue;
}

update_option( $setting['option'], $data[ $exposed_name ] );
}

return $this->get_setting_values( $named );
}

/**
* Executes the `core/settings-get` ability.
*
Expand All @@ -115,7 +247,7 @@ private function execute_settings_get( $input = array() ): array {
$group = isset( $input['group'] ) && is_string( $input['group'] ) ? $input['group'] : '';
$fields = rest_sanitize_array( $input['fields'] ?? array() );

$result = array();
$requested = array();
foreach ( $this->exposed_settings as $exposed_name => $setting ) {
if ( '' !== $group && $setting['group'] !== $group ) {
continue;
Expand All @@ -124,21 +256,35 @@ private function execute_settings_get( $input = array() ): array {
continue;
}

$requested[ $exposed_name ] = $setting;
}

return $this->get_setting_values( $requested );
}

/**
* Reads the current values of the given exposed settings.
*
* A setting without a value, or whose value does not match its schema, is left out.
*
* @since 7.3.0
*
* @param array<string, array{option: string, group: string, default: mixed, schema: array<string, mixed>}> $settings Exposed settings, keyed by exposed name.
* @return array<string, mixed> Map of exposed setting name to current value.
*/
private function get_setting_values( array $settings ): array {
$result = array();
foreach ( $settings as $exposed_name => $setting ) {
/*
* 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'] );
$value = $this->get_stored_value( $setting, $setting['default'] );
if ( null === $value ) {
continue;
}

// WordPress stores false as '', which the boolean schema rejects.
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.
Expand All @@ -159,6 +305,75 @@ private function execute_settings_get( $input = array() ): array {
return $result;
}

/**
* Reads the stored value of an exposed setting.
*
* @since 7.3.0
*
* @param array{option: string, group: string, default: mixed, schema: array<string, mixed>} $setting The exposed setting.
* @param mixed $default_value The value to return when the option does not exist.
* @return mixed The stored value, or the default value.
*/
private function get_stored_value( array $setting, $default_value ) {
$value = get_option( $setting['option'], $default_value );

// WordPress stores false as '', which the boolean schema rejects.
if ( '' === $value && 'boolean' === $setting['schema']['type'] ) {
return false;
}

return $value;
}

/**
* Builds the input schema for the `core/settings-update` ability.
*
* Each writable setting accepts a value of its own schema, or null.
*
* @since 7.3.0
*
* @return array<string, mixed> The input JSON Schema.
*/
private function get_settings_update_input_schema(): array {
return array(
'type' => 'object',
'properties' => array(
'data' => array(
'type' => 'object',
'description' => __( 'Settings to update, keyed by setting name. A null value deletes the stored value of a setting.' ),
'properties' => array_map(
fn( array $schema ): array => $this->nullable_schema( $schema ),
wp_list_pluck( $this->writable_settings, 'schema' )
),
'additionalProperties' => false,
'minProperties' => 1,
),
),
'required' => array( 'data' ),
'additionalProperties' => false,
);
}

/**
* Allows null in a setting's value schema.
*
* Adds `null` to the type, and to the allowed values when the schema lists them. Nested
* schemas are not changed.
*
* @since 7.3.0
*
* @param array<string, mixed> $schema The value JSON Schema.
* @return array<string, mixed> The value JSON Schema that also accepts null.
*/
private function nullable_schema( array $schema ): array {
$schema['type'] = array( $schema['type'], 'null' );
if ( isset( $schema['enum'] ) ) {
$schema['enum'][] = null;
}

return $schema;
}

/**
* Builds the input schema for the `core/settings-get` ability: optional filters by group and/or name.
*
Expand Down Expand Up @@ -196,19 +411,22 @@ private function get_settings_get_input_schema( array $groups, array $field_name
}

/**
* Builds the output schema for the `core/settings-get` ability.
* Builds the output schema shared by the settings abilities.
*
* 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.
* No setting is marked required because both abilities return a subset: `core/settings-get`
* the settings its `group` and `fields` inputs ask for, and `core/settings-update` the settings
* named in the call. A setting without a value, or whose value does not match its schema, is
* also left out.
*
* @since 7.2.0
* @since 7.3.0
*
* @param string $description The description of the output.
* @return array<string, mixed> The output JSON Schema.
*/
private function get_settings_get_output_schema(): array {
private function get_settings_output_schema( string $description ): array {
return array(
'type' => 'object',
'description' => __( 'A map of setting name to its current value.' ),
'description' => $description,
'properties' => wp_list_pluck( $this->exposed_settings, 'schema' ),
'additionalProperties' => false,
);
Expand Down
6 changes: 5 additions & 1 deletion src/wp-includes/option.php
Original file line number Diff line number Diff line change
Expand Up @@ -3039,6 +3039,7 @@ function _wp_register_initial_settings_for_abilities(): void {
* Please consider writing more inclusive code.
* @since 6.6.0 Added the `label` argument.
* @since 7.2.0 Added the `show_in_abilities` argument.
* @since 7.3.0 Settings exposed with the `show_in_abilities` argument can be updated through the Abilities API.
*
* @global array $new_allowed_options
* @global array $wp_registered_settings
Expand All @@ -3061,10 +3062,13 @@ function _wp_register_initial_settings_for_abilities(): void {
* @type bool|array $show_in_rest Whether data associated with this setting should be included in the
* REST API. When registering complex settings, this argument may
* optionally be an array with a 'schema' key.
* @type bool|array $show_in_abilities Whether this setting should be exposed through the Abilities API.
* @type bool|array $show_in_abilities Whether this setting should be exposed through the Abilities API,
* where users who can manage options can read and update it.
* When true, it uses the same name and schema as `$show_in_rest`.
* It may also be an array with 'name' and 'schema' keys, used instead of
* `$show_in_rest` rather than merged with it.
* A setting whose schema sets 'readonly' to true can be read but
* not updated.
* Settings registered after abilities initialize are not exposed.
* @type mixed $default Default value when calling `get_option()`.
* }
Expand Down
Loading
Loading