Add a core/settings-update ability - #764

jorgefilipecosta · 2026-06-23T14:52:43Z

What?

Adds core/settings-update next to core/settings-get.

Why?

Agents can read the settings exposed to abilities but not change them. This lets them update those settings under the same rules as the REST API.

How?

The ability lives in includes/Abilities/Settings/Settings.php, behind the Custom Abilities experiment with core/settings-get. Neither ability registers when no setting is exposed.
Input: a map of setting name to its new value, for any setting core/settings-get reads except url and email (siteurl and admin_email), which stay read-only for now: a wrong site URL makes wp-admin unreachable, and wp-admin only changes the admin email after the new address confirms it. As in the settings endpoint, only users who can manage privacy options, network admins on multisite, can change page_for_privacy_policy. For a setting with a registered default (among core settings, language, use_smilies and posts_per_page), null resets the setting to that default. Unknown names, empty input and null for a setting without a default are rejected; the endpoint deletes such a setting, leaving it without a value.
It mirrors WP_REST_Settings_Controller::update_item(). Every value is sanitized against its schema before any is written; the REST API does this through each setting's sanitize_callback arg option, while the Abilities API only validates. Settings are written in registration order, objects reject undeclared properties, and null is refused with settings_invalid_stored_value while the stored value fails validation. Unlike the endpoint, which checks stored values while writing and keeps the settings it already wrote, every check runs before any write, so an error leaves every setting unchanged. A value that sanitizing makes invalid is refused with settings_invalid_param, where the endpoint stores it: %ab@x.co in a setting with the email format would be stored as @x.co. null resets a boolean stored as false, which WordPress saves as ''; the endpoint refuses that reset. The endpoint's null only deletes the stored value, while the ability then stores the registered default: core registers its settings, and so their defaults, only in REST and abilities requests, so after the endpoint's { "posts_per_page": null } other requests read false and show one post per page. For the same reason, a value that matches the registered default is stored when no value is, where update_option() stores nothing. A setting with no stored value reads as its registered default, so null can reset it, where the endpoint refuses that null with a 500. The endpoint also skips a privacy policy page change from users who cannot manage privacy options, while the ability refuses the update with settings_cannot_manage_privacy_options. Error codes use settings_ in place of rest_, and the REST-only filters do not run.
Output: only the updated settings, as core/settings-get reads them after the update; the endpoint answers with the whole settings object, which core/settings-get still returns. core/settings-get now sanitizes each stored value against its schema and leaves out a value the schema rejects, before or after sanitizing, instead of failing for every setting; the endpoint answers null for such a value. Without that, a setting without a default that the endpoint reset to null, such as default_ping_status, would fail core/settings-get for every setting. A boolean stored as false, which WordPress saves as '', reads as false.
Names: as in core (Abilities API: Add a core/settings-get ability wordpress-develop#12141), a setting flagged with show_in_abilities => true takes its name and schema from show_in_rest, and every core setting is flagged with true. Both abilities, and the deprecated core/read-settings alias, now use the settings endpoint's names: title, description, url, email, timezone, language and page_for_privacy_policy replace blogname, blogdescription, siteurl, admin_email, timezone_string, WPLANG and wp_page_for_privacy_policy. url gets the endpoint's uri format, which the abilities client accepts since WordPress 7.1.
It is destructive but not idempotent, so it stays on POST: the DELETE method cannot carry null.
The tests port the settings endpoint's update tests under their core names. A throwaway harness ran 23 updates through both the endpoint and the ability on WordPress 7.1.2. The results match, apart from the differences above.

Testing Instructions

Enable the Custom Abilities experiment.
Run core/settings-update with { "title": "New name" }, then with { "posts_per_page": null }. The first call returns { "title": "New name" }, the second { "posts_per_page": 10 }. { "url": "https://example.com" } and { "default_ping_status": null } are rejected.
npm run test:php -- --filter 'SettingsTest|Gated_AbilitiesTest|Custom_AbilitiesTest'
npm run test:e2e -- tests/e2e/specs/abilities/core-settings-update.spec.js

Changelog Entry

Added - New core/settings-update ability that mirrors the REST API settings endpoint.
Changed - core/settings-get and its deprecated core/read-settings alias now name settings as the REST API settings endpoint does, for example title instead of blogname and url instead of siteurl.
Changed - The Settings_Get gated ability class is now Settings, so code that removes it with the wpai_gated_abilities filter needs the new class name.

AI disclosure: the latest fixes come from an AI-assisted code review of the core port, and were drafted with AI assistance (Claude Code) and reviewed by me.

github-actions · 2026-06-23T14:52:53Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: jorgefilipecosta <jorgefilipecosta@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>
Co-authored-by: dkotter <dkotter@git.wordpress.org>
Co-authored-by: jeffpaul <jeffpaul@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

github-actions · 2026-06-23T14:57:24Z

✅ WordPress Plugin Check Report

✅ Status: Passed

📊 Report

All checks passed! No errors or warnings found.

🤖 Generated by WordPress Plugin Check Action • Learn more about Plugin Check

codecov · 2026-06-23T14:58:41Z

Codecov Report

❌ Patch coverage is 99.37500% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 81.83%. Comparing base (19d5670) to head (4f0d1e6).
⚠️ Report is 1 commits behind head on develop.

Files with missing lines	Patch %	Lines
includes/Abilities/Settings/Settings.php	99.29%	1 Missing ⚠️

Additional details and impacted files

@@              Coverage Diff              @@
##             develop     #764      +/-   ##
=============================================
+ Coverage      81.67%   81.83%   +0.15%     
- Complexity      3103     3115      +12     
=============================================
  Files            129      129              
  Lines          12334    12426      +92     
=============================================
+ Hits           10074    10169      +95     
+ Misses          2260     2257       -3

Flag	Coverage Δ
unit	`81.83% <99.37%> (+0.15%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

jeffpaul · 2026-07-16T16:59:10Z

I'd like to see #863 land alongside this specific PR (and any others that aren't explicitly read abilities), to help ensure folks enabling these sorts of abilities are doing so knowingly.

dkotter · 2026-10-07T00:18:10Z

+			 * setting; the settings endpoint answers null for it. A setting without a registered
+			 * default that `core/settings-update` reset to null reads this way.
+			 */
+			if ( is_wp_error( rest_validate_value_from_schema( $value, $setting['schema'] ) ) ) {


So this may not matter but I think this will leave out boolean settings that have been turned off, as WordPress often saves those as an empty string instead of false. The validation here will fail for those so those settings will never be returned (previous to this change, they were cast to false)

dkotter · 2026-10-07T00:19:12Z

+				 * The endpoint checks this while writing; checking it here keeps the earlier
+				 * settings in the input from being written when the update fails.
+				 */
+				if ( '' === $invalid_stored && is_wp_error( rest_validate_value_from_schema( get_option( $args['option_name'], false ), $args['schema'] ) ) ) {


Similar thing here. If I want to reset a boolean-type setting to null, this check fails. May be another thing we don't care to support though

dkotter · 2026-10-07T00:20:17Z

+	 *                                                  the update, an empty object when none can be read back,
+	 *                                                  or a WP_Error.
+	 */
+	public function execute_update_settings( $input = array() ) {


Do we need/want a check here for READ_ONLY_OPTIONS, in case a call skipped the input validation?

dkotter · 2026-10-07T00:21:32Z

-				'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 ),
+			$settings[ empty( $show['name'] ) ? $option_name : $show['name'] ] = array(


Any risk here for someone passing a name that isn't a string? Previously we had a is_string check that would have handled that but that's removed here. This could lead to fatal errors if someone can pass in a non-string value

dkotter · 2026-10-07T00:23:25Z

+			if ( is_null( $args['value'] ) ) {
+				delete_option( $args['option_name'] );
+			} else {
+				update_option( $args['option_name'], $args['value'] );


Should we check if update_option was successful? And if not, report that instead of reporting success?

dkotter · 2026-10-07T00:25:00Z

+			$options[ $name ] = $args;
+		}
+
+		if ( $invalid_params ) {


Can this code ever be triggered? Since we validate params earlier I think this might be dead code

dkotter · 2026-10-07T00:25:18Z

+	 * the new address confirms it.
+	 *
+	 * @since x.x.x
+	 * @var string[]


Suggested change

* @var string[]

* @var list<string>

WordPress stores false as '', which rest_is_boolean() rejects. Since 3fa0775 validates the stored value before sanitizing it, core/settings-get left out every boolean setting whose value is false, including one core/settings-update had just written and a Settings API checkbox saved unchecked. cast_value() used to read it as false, while the settings endpoint answers null for it. Read '' as false for a boolean setting before validating it, and test that it reads back as false.

WP_REST_Settings_Controller::get_registered_options() runs rest_default_additional_properties_to_false() on every setting schema, so objects reject properties they do not declare when the endpoint reads a value as well as when it writes one. The abilities only did it for writes: core/settings-get returned a stored object with an undeclared property whole, where the endpoint answers null, and that value could not be sent back to core/settings-update. Close the schema once in value_schema(), so both abilities read and write against it. The output schemas now declare additionalProperties false on objects, as the endpoint's schema does. The core class WP_Abilities_Settings gets the same change, so the two stay identical.

The input schema accepts an object, but execute_get_settings() replaced anything other than an array with an empty one, so a PHP caller that passed its filters as an object, such as (object) array( 'group' => 'reading' ), got every setting back. Normalize the input with rest_sanitize_object(), as core/settings-update already does. The core class WP_Abilities_Settings gets the same change.

The class docblock said core/settings-update writes the same settings core/settings-get reads, which leaves out siteurl and admin_email, and Show_In_Abilities named only core/settings-get as a consumer of the flag. The execute_update_settings() docblock described its checks in one long sentence; list them in the order they run.

The core class WP_Abilities_Settings switches the core/settings-get input default to array(), as the other core abilities use. Core sends that default as {} on the abilities endpoint and, since WordPress 7.1, through the AI client, and an array cannot be changed in place by a wp_ability_normalize_input filter the way the shared object can. The plugin keeps the object, because the WordPress 7.0 AI client sends ability schemas as is, where array() would go out as []. Mark it with a Plugin: comment, as the class does for its other differences from core.

The core class WP_Abilities_Settings sets only the public meta flag on core/settings-get, which WordPress 7.1 also reads as show_in_rest. WordPress 7.0 does not read public, so the plugin keeps show_in_rest. Mark it with a Plugin: comment, as the class does for its other differences from core.

gziolo · 2026-10-07T12:05:45Z

+						// which cannot carry null.
+						'idempotent'  => false,
+					),
+					'show_in_rest' => true,


Could we use 'public' => true here, replacing 'show_in_rest' => true once WordPress 7.0 compatibility is no longer needed? On WordPress 7.1+, public also enables REST exposure by default, while show_in_rest alone leaves public false, so the default MCP adapter does not expose this ability. This would align settings-update with settings-get and the other core abilities updated in #1122. If we still need WordPress 7.0 support, we should add public and retain show_in_rest for that compatibility.

Port the core change in WordPress/wordpress-develop#12141 (749c2eb430). When show_in_abilities is true, a setting now takes the name and schema from show_in_rest; an array is still used as is. Show_In_Abilities flags every core setting with true, as option.php does, so core/settings-get, its deprecated core/read-settings alias, and core/settings-update use the settings endpoint's names: blogname is title, blogdescription is description, siteurl is url, admin_email is email, timezone_string is timezone, WPLANG is language, and wp_page_for_privacy_policy is page_for_privacy_policy. The email format and the comment status enums now come from show_in_rest, and siteurl gains its uri format, which the abilities client accepts since WordPress 7.1. Port core's tests for the REST names and the inherited exposure, use the new names in the other tests and the e2e specs, and drop the Show_In_Abilities test for a curated array value, since none is left. Co-authored-by: Grzegorz Ziolkowski <grzegorz@gziolo.pl>

Port the core change in WordPress/wordpress-develop#12141 (e7e6a2340e), which matches the other core abilities. Since WordPress 7.1, wp_prepare_json_schema_for_client() sends an empty object default as {} on the abilities endpoint and through the AI client, and the execute callback gets an array when no input is given. Drop the Plugin: comment that kept the object for WordPress 7.0, so the class matches core again. Co-authored-by: Grzegorz Ziolkowski <grzegorz@gziolo.pl>

Port the core change in WordPress/wordpress-develop#12141 (30742fc248). The input schema validates `fields` with rest_is_array(), which also accepts a comma-separated string, but execute_get_settings() replaced anything other than an array with an empty one, so a PHP caller that passed 'title,posts_per_page' got every setting back. REST requests were not affected, because the run endpoint converts the input to the schema types first. Normalize the list with rest_sanitize_array().

Port the core docs change in WordPress/wordpress-develop#12141 (4620fbcaed). An array replaces the show_in_rest name and schema entirely, so a setting that only sets a name for abilities also drops its REST schema, such as an email format. Say so where Show_In_Abilities describes the values it can set.

Port the core test in WordPress/wordpress-develop#12141 (f5cf4af483). show_in_abilities => true reuses the show_in_rest name and schema, so guard the opt-in rule next to it: a setting shown in the REST API without show_in_abilities is not exposed.

… exposed Port the core docs change in WordPress/wordpress-develop#12141 (89ca6e70f4). The abilities registry can initialize while init is still running, for example when a plugin uses it at an earlier init priority, so the docs were wrong to call registering a setting on init reliable. Say that settings registered after the abilities register are not exposed, and drop the comments that only repeat that the exposed settings are computed once.

Port the core change in WordPress/wordpress-develop#12141 (a4e7ea0948). It does not: it reads values with a plain get_option() call, without the rest_pre_get_setting filter or the schema default that /wp/v2/settings passes, and it leaves out a value the endpoint answers with null. Describe what the ability does instead.

Port the core change in WordPress/wordpress-develop#12141 (f454c10bbf). PHP turns a numeric array key, such as a setting named 123, into an integer. The fields enum then listed the integer, so input validation rejected the name passed as a string, and the strict in_array() check did not match it either. Cast the names to strings, and test with a numeric setting name. core/settings-update builds its answer from the keys of the settings it wrote, which are integers for such names, so pass them to core/settings-get as strings too. Without that, the string check would leave a numeric setting out of the answer.

Port the core change in WordPress/wordpress-develop#12141 (a999491872). Stored values were only validated before sanitizing, but rest_sanitize_value_from_schema() can turn a valid value into one the schema rejects. For example, sanitize_text_field() turns the email %ab@x.co into @x.co. Output validation then failed the whole call instead of leaving out that one setting. Validate the sanitized value too.

@SInCE

The comment above the schema checks in execute_get_settings() had a sentence about core/settings-update resets, the only difference from core's method besides the @SInCE lines, and it carried no Plugin: marker. Drop it.

null deletes the stored value. Among the core settings only language, use_smilies and posts_per_page register a default, so for the others a null left the setting without a value: the site title, the date format or the front page setting read as false, and both abilities then left the setting out. The description promised that the setting falls back to its default. Add null to the type, and to any enum, only for a setting with a registered default, so the input schema shows which settings can be reset and the Abilities API rejects a null for the others. The settings endpoint accepts null for every setting.

rest_sanitize_value_from_schema() can turn a valid value into one the schema rejects: sanitize_text_field() turns the email %ab@x.co into @x.co. The ability stored that value, and since core/settings-get now leaves out such values, the answer was {} with nothing to say why. Validate the sanitized value too, and refuse it with settings_invalid_param before any setting is written. The settings endpoint stores it.

WordPress stores false as '', which the boolean schema rejects. A null for a boolean turned off in an earlier request was then refused with settings_invalid_stored_value, although core/settings-get reads the setting as false, so a client never sees an invalid value to protect. Read the stored value the way core/settings-get does before checking it. The settings endpoint refuses that null, since it answers null for the setting.

A show_in_abilities (or show_in_rest) name that is not a string, such as an array, was used as an array key, which is a fatal error while the abilities register, so one bad registration broke every ability. develop checked the name with is_string(). Use the option name instead, as for an empty name. Core's WP_Abilities_Settings, and the settings endpoint, fail the same way, so this is marked as a plugin difference.

WP_UnitTestCase backs up $wp_actions once and restores it after every test, so the two tests that set the rest_api_init count no longer save and restore it themselves.

rest_validate_value_from_schema() ignores an empty enum, so a setting whose schema has `enum => array()`, such as a list computed when the setting registers that came out empty, accepts any value through core/settings-get and the settings endpoint. For a setting with a default, update_value_schema() appended null to it, which left `enum => array( null )`, so the ability refused every value but null. Add null only to an enum that is not empty.

…alue The comment said the check keeps a client that sends a response back from deleting values that fail validation. core/settings-get never answers null, it leaves such values out, so that only holds for answers from the settings endpoint, whose setting names the abilities now share. Say so, and note that a repeated null can be refused once the stored value is gone, since get_option() is passed false as the default.

The input schema alone kept url and email read-only and refused null for a setting without a default. A wp_ability_validate_input filter can skip that validation, and then {"url": ...} wrote siteurl before the output check failed, a null deleted default_ping_status, and an input with only unknown names answered with every setting, since an empty `fields` filter means all of them. Skip read-only settings in the write loop, check each sanitized value against the input schema rather than the setting's schema, and answer with no setting when nothing was written.

A null deleted the stored value, as the settings endpoint does, so the setting fell back to its registered default. That default only applies in requests that register the setting, and core registers its own settings only in REST and abilities requests. After {"posts_per_page": null}, the ability answered 10 while other requests read false and showed one post per page, and sending 10 again stored nothing, since update_option() skips a value that matches the registered default when no value is stored. Delete the stored value, then store the registered default, so every request reads it. The delete comes first because sanitize_option() turns a language that is not installed, such as the en_US default, into the current value. Also store a value that update_option() skips that way.

The stored-value check read the value with false as the default, as the settings endpoint does, so a setting with no stored value failed validation and null was refused with a 500: language on a site without a WPLANG row, or posts_per_page after the endpoint's null deleted it. Since null now stores the default, that refusal blocked the very reset that repairs such a setting. Read a missing value as the registered default, as core/settings-get and the endpoint answer it. A stored value that fails validation is still refused.

The fallback after update_option() added the value whenever no value was stored afterwards, including a value update_option() refused on purpose: a pre_update_option_{$option} filter that turned the update back was bypassed, and a language that is not installed left a new en_US row where the settings endpoint stores nothing. Add the value only when it matches the registered default, the one case where update_option() stores nothing because no value is stored.

jeffpaul added this to the 1.2.0 milestone Jun 23, 2026

jeffpaul added this to WordPress AI Roadmap Jun 23, 2026

github-project-automation Bot moved this to Triage in WordPress AI Roadmap Jun 23, 2026

jeffpaul moved this from Triage to Needs review in WordPress AI Roadmap Jun 23, 2026

jeffpaul requested review from dkotter and gziolo June 23, 2026 14:59

gziolo reviewed Jun 24, 2026

View reviewed changes

Comment thread includes/Abilities/Settings/Settings.php Outdated

gziolo reviewed Jun 24, 2026

View reviewed changes

Comment thread includes/Abilities/Settings/Settings.php

gziolo reviewed Jun 24, 2026

View reviewed changes

Comment thread includes/Abilities/Settings/Settings.php Outdated

gziolo reviewed Jun 24, 2026

View reviewed changes

Comment thread includes/Abilities/Settings/Settings.php Outdated

dkotter assigned jorgefilipecosta Jun 24, 2026

jeffpaul modified the milestones: 1.2.0, 1.3.0 Jul 13, 2026

jeffpaul moved this from Needs review to In progress in WordPress AI Roadmap Jul 13, 2026

jeffpaul mentioned this pull request Jul 13, 2026

New Experiment: Abilities toggle #863

Closed

1 task done

gziolo mentioned this pull request Jul 17, 2026

WordPress Core Abilities #40

Open

6 of 7 tasks

jeffpaul mentioned this pull request Aug 10, 2026

Release version 1.3.0 #924

Closed

48 tasks done

dkotter modified the milestones: 1.3.0, 1.4.0 Aug 12, 2026

jeffpaul modified the milestones: 1.4.0, 1.5.0 Sep 17, 2026

jorgefilipecosta force-pushed the add/core-manage-settings-ability branch from 68d5383 to 1174887 Compare October 1, 2026 17:00

jorgefilipecosta requested a review from a team as a code owner October 1, 2026 17:00

jorgefilipecosta changed the title ~~Add a core/manage-settings ability~~ Add a core/settings-update ability Oct 1, 2026

jorgefilipecosta changed the base branch from develop to update/rename-settings-get-ability October 1, 2026 17:01

jorgefilipecosta requested a review from gziolo October 6, 2026 22:06

dkotter requested changes Oct 7, 2026

View reviewed changes

jorgefilipecosta added 6 commits October 7, 2026 04:31

gziolo reviewed Oct 7, 2026

View reviewed changes

jorgefilipecosta and others added 21 commits October 7, 2026 13:53

Keep the core/settings-get comment identical to core

67e3398

The comment above the schema checks in execute_get_settings() had a sentence about core/settings-update resets, the only difference from core's method besides the @SInCE lines, and it carried no Plugin: marker. Drop it.

Drop the rest_api_init restore from the settings registration tests

e22f37a

WP_UnitTestCase backs up $wp_actions once and restores it after every test, so the two tests that set the rest_api_init count no longer save and restore it themselves.

Conversation

jorgefilipecosta commented Jun 23, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Testing Instructions

Changelog Entry

Uh oh!

github-actions Bot commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 23, 2026

✅ WordPress Plugin Check Report

📊 Report

Uh oh!

codecov Bot commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jeffpaul commented Jul 16, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jorgefilipecosta commented Jun 23, 2026 •

edited by github-actions Bot

Loading

github-actions Bot commented Jun 23, 2026 •

edited

Loading

codecov Bot commented Jun 23, 2026 •

edited

Loading