Skip to content

Abilities API: Add a core/manage-settings ability #90

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jorgefilipecosta wants to merge 11 commits into
base: add/core-settings-ability
Choose a base branch
from
Open

Abilities API: Add a core/manage-settings ability #90

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
f806ee8
Abilities API: Add a core/settings ability
jorgefilipecosta Jun 9, 2026
7e9ff8d
Abilities API: rename the core/settings 'slugs' input to 'settings'
jorgefilipecosta Jun 15, 2026
fa3ec96
Abilities API: cover a custom registered setting in the core/settings…
jorgefilipecosta Jun 15, 2026
a4c3f98
Abilities API: refine the core/settings ability per review.
jorgefilipecosta Jun 17, 2026
2fab109
Abilities API: use list<string> for the core/settings input schema do…
jorgefilipecosta Jun 19, 2026
2746171
Abilities API: drop the unreachable recompute branch in execute_get_s…
jorgefilipecosta Jun 19, 2026
6eea893
Abilities API: document the show_in_abilities registration-timing con…
jorgefilipecosta Jun 19, 2026
b2e95b9
Abilities API: scope the WP_Settings_Abilities class.
jorgefilipecosta Jun 22, 2026
6419a95
Abilities API: make WP_Settings_Abilities instance-based.
jorgefilipecosta Jun 22, 2026
54d3259
Abilities API: add a core/manage-settings ability.
jorgefilipecosta Jun 23, 2026
45ace74
Abilities API: test the core/manage-settings ability.
jorgefilipecosta Jun 23, 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
5 changes: 5 additions & 0 deletions src/wp-includes/abilities.php
View file
Open in desktop
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-settings-abilities.php';

/**
* Registers the core ability categories.
*
Expand Down Expand Up @@ -351,4 +353,7 @@ function wp_register_core_abilities(): void {
),
)
);

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

declare( strict_types = 1 );

/**
* Core class used to register settings-related abilities.
*
* Provides the read-only `core/settings` ability and the write-oriented `core/manage-settings`
* ability, plus the shared building blocks (exposed-settings discovery, schema generation, value
* casting) that back both.
*
* This class is part of WordPress' internal implementation of the core abilities and is
* not part of the public API. It may be changed or removed at any time without notice.
* Do not use it directly or rely on its existence.
*
* @since 7.1.0
*
* @access private
*/
final class WP_Settings_Abilities {

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

/**
* Settings exposed through the Abilities API, computed once at registration.
*
* Cached so the input/output schema and the executed result derive from the exact same
* structure, and {@see get_registered_settings()} is only walked once per request.
*
* @since 7.1.0
* @var array<string, array{option: string, group: string, default: mixed, schema: array<string, mixed>}>|null
*/
private $exposed_settings = null;

/**
* Registers all settings abilities.
*
* Must run on the `wp_abilities_api_init` hook.
*
* @since 7.1.0
*/
public function register(): void {
$this->register_get_settings();
$this->register_manage_settings();
}

/**
* Registers the read-only `core/settings` ability.
*
* @since 7.1.0
*/
private function register_get_settings(): void {
// Compute once; execute_get_settings() reuses this exact structure.
$this->exposed_settings = $this->get_exposed_settings();

$settings = $this->exposed_settings;
$field_names = array_keys( $settings );
$groups = array();
$properties = array();
foreach ( $settings as $exposed_name => $setting ) {
$properties[ $exposed_name ] = $setting['schema'];
if ( '' === $setting['group'] || in_array( $setting['group'], $groups, true ) ) {
continue;
}
$groups[] = $setting['group'];
}

wp_register_ability(
'core/settings',
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.' ),
'category' => self::CATEGORY,
'input_schema' => $this->get_settings_input_schema( $groups, $field_names ),
'output_schema' => array(
'type' => 'object',
'description' => __( 'A map of setting name to its current value.' ),
'properties' => $properties,
'additionalProperties' => false,
),
'execute_callback' => array( $this, 'execute_get_settings' ),
'permission_callback' => array( $this, 'has_permission' ),
'meta' => array(
'annotations' => array(
'readonly' => true,
'destructive' => false,
'idempotent' => true,
),
'show_in_rest' => true,
),
)
);
}

/**
* Registers the write-oriented `core/manage-settings` ability.
*
* The input and output schemas reuse each exposed setting's own schema, so every setting
* readable via `core/settings` is also writable through this ability.
*
* @since 7.1.0
*/
private function register_manage_settings(): void {
$settings = (array) $this->exposed_settings;
$properties = array();
foreach ( $settings as $exposed_name => $setting ) {
$properties[ $exposed_name ] = $setting['schema'];
}

wp_register_ability(
'core/manage-settings',
array(
'label' => __( 'Manage Settings' ),
'description' => __( 'Updates one or more WordPress settings exposed to abilities. Accepts a map of setting name to its new value and returns the updated values.' ),
'category' => self::CATEGORY,
'input_schema' => array(
'type' => 'object',
'description' => __( 'A map of setting name to the new value to store. At least one setting is required.' ),
'properties' => $properties,
'minProperties' => 1,
'additionalProperties' => false,
),
'output_schema' => array(
'type' => 'object',
'description' => __( 'A map of each updated setting name to its new value.' ),
'properties' => $properties,
'additionalProperties' => false,
),
'execute_callback' => array( $this, 'execute_manage_settings' ),
'permission_callback' => array( $this, 'has_permission' ),
'meta' => array(
'annotations' => array(
'readonly' => false,
'destructive' => false,
'idempotent' => true,
),
'show_in_rest' => true,
),
)
);
}

/**
* Executes the `core/settings` ability.
*
* @since 7.1.0
*
* @param mixed $input Optional. The ability input. Default empty array.
* @return array<string, mixed> Map of exposed setting name to current value.
*/
public function execute_get_settings( $input = array() ): array {
$input = is_array( $input ) ? $input : array();

$settings = $this->exposed_settings;
if ( null === $settings ) {
// The cache is populated in register_get_settings() before the ability is
// registered, so this is unreachable in practice; bail defensively otherwise.
return array();
}

$group = isset( $input['group'] ) && is_string( $input['group'] ) ? $input['group'] : '';
$fields = isset( $input['fields'] ) && is_array( $input['fields'] ) ? $input['fields'] : array();

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

$type = isset( $setting['schema']['type'] ) && is_string( $setting['schema']['type'] ) ? $setting['schema']['type'] : 'string';
$value = get_option( $setting['option'], $setting['default'] );

$result[ $exposed_name ] = $this->cast_value( $value, $type );
}

return $result;
}

/**
* Executes the `core/manage-settings` ability.
*
* The Abilities API validates the input against the registered input schema (each setting's own
* value schema, with `additionalProperties` disabled) before this runs, so every value reaching
* here is known and valid; an invalid value aborts the call before any option is written. Each
* value is sanitized against its schema and stored, then read back and cast for the response.
*
* @since 7.1.0
*
* @param mixed $input The ability input: a map of exposed setting name to its new value.
* @return array<string, mixed> Map of each updated setting name to its stored value.
*/
public function execute_manage_settings( $input = array() ): array {
$input = is_array( $input ) ? $input : array();

$settings = $this->exposed_settings;
if ( null === $settings ) {
// The cache is populated in register_get_settings() before the ability is
// registered, so this is unreachable in practice; bail defensively otherwise.
return array();
}

$result = array();
foreach ( $input as $exposed_name => $value ) {
if ( ! is_string( $exposed_name ) || ! isset( $settings[ $exposed_name ] ) ) {
// `additionalProperties: false` already rejects unknown keys upstream; guard defensively.
continue;
}

$setting = $settings[ $exposed_name ];

// Sanitize against the declared schema before storing; update_option() additionally
// runs the setting's own registered sanitize_callback.
$value = rest_sanitize_value_from_schema( $value, $setting['schema'], $exposed_name );

update_option( $setting['option'], $value );

$type = isset( $setting['schema']['type'] ) && is_string( $setting['schema']['type'] ) ? $setting['schema']['type'] : 'string';
$stored = get_option( $setting['option'], $setting['default'] );

$result[ $exposed_name ] = $this->cast_value( $stored, $type );
}

return $result;
}

/**
* Checks whether the current user may use the settings abilities.
*
* @since 7.1.0
*
* @return bool True if the current user can manage options.
*/
public function has_permission(): bool {
return current_user_can( 'manage_options' );
}

/**
* Builds the input schema for the 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.1.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_input_schema( array $groups, array $field_names ): array {
return array(
'type' => 'object',
// Object (not array()) so the serialized schema default is {}, consistent with type:object.
'default' => (object) array(),
'properties' => array(
'group' => array(
'type' => 'string',
'enum' => $groups,
'description' => __( 'Return only settings that belong to this settings group.' ),
),
'fields' => array(
'type' => 'array',
'items' => array(
'type' => 'string',
'enum' => $field_names,
),
'description' => __( 'Return only the settings with these names.' ),
),
),
'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. Each entry is keyed by its exposed name and carries the
* underlying option name, the settings group, the registration default, and a JSON Schema
* describing the value.
*
* @since 7.1.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 ) {
$show = $args['show_in_abilities'] ?? false;
if ( empty( $show ) ) {
continue;
}

$option_name = (string) $option_name;
$exposed_name = is_array( $show ) && isset( $show['name'] ) && is_string( $show['name'] ) && '' !== $show['name'] ? $show['name'] : $option_name;

$settings[ $exposed_name ] = array(
'option' => $option_name,
'group' => isset( $args['group'] ) && is_string( $args['group'] ) ? $args['group'] : '',
'default' => array_key_exists( 'default', $args ) ? $args['default'] : false,
'schema' => $this->value_schema( $args, $show ),
);
}

return $settings;
}

/**
* Builds the JSON Schema describing a single setting's value.
*
* @since 7.1.0
*
* @param array<string, mixed> $args The setting registration arguments.
* @param bool|array<string, mixed> $show The setting's `show_in_abilities` value.
* @return array<string, mixed> The value JSON Schema.
*/
private function value_schema( array $args, $show ): array {
$schema = array(
'type' => isset( $args['type'] ) && is_string( $args['type'] ) ? $args['type'] : 'string',
);
if ( ! empty( $args['label'] ) ) {
$schema['title'] = $args['label'];
}
if ( ! empty( $args['description'] ) ) {
$schema['description'] = $args['description'];
}
if ( is_array( $show ) && isset( $show['schema'] ) && is_array( $show['schema'] ) ) {
/** @var array<string, mixed> $show_schema */
$show_schema = $show['schema'];
$schema = array_merge( $schema, $show_schema );
}

return $schema;
}

/**
* Casts a stored option value to the type declared in its settings registration.
*
* @since 7.1.0
*
* @param mixed $value The raw option value.
* @param string $type The registered setting type.
* @return mixed The value cast to the declared type.
*/
private function cast_value( $value, string $type ) {
switch ( $type ) {
case 'boolean':
return (bool) $value;
case 'integer':
return is_scalar( $value ) ? (int) $value : 0;
case 'number':
return is_scalar( $value ) ? (float) $value : 0.0;
case 'array':
return is_array( $value ) ? $value : array();
case 'object':
// Cast to object so an empty/non-array value serializes as {} (not []) and
// satisfies the `object` output schema validated by execute().
return (object) ( is_array( $value ) ? $value : array() );
default:
return is_scalar( $value ) ? (string) $value : $value;
}
}
}
Loading
Loading