Abilities API: Add a core/settings-get ability

[jorgefilipecosta]

What?

Port of WordPress/ai#691 (renamed in WordPress/ai#1087), part of WordPress/ai#40. Adds a read-only core/settings-get ability.

• register_setting() gets a show_in_abilities argument, false by default. true reuses the setting's REST name and schema, so blogname is exposed as title, as in /wp/v2/settings. An array with name and schema keys is used instead. register_initial_settings() flags 19 settings, such as blogname, posts_per_page, and default_comment_status.
• core/settings-get returns the exposed settings as a flat map of name to value, optionally filtered by group, fields, or both. It requires manage_options.
• Each value is validated against its schema before and after sanitizing. A value that fails is left out, so one bad stored value does not fail the whole call.
• The initial settings are also registered on wp_abilities_api_init, so the ability finds them on cron, WP-CLI, and before rest_api_init.
• The code lives in the private WP_Abilities_Settings class, which the planned core/settings-update ability (Add a core/settings-update ability ai#764) can share.

Testing

Verify unit tests are passing:

npm run test:php -- --group abilities-api

Manual test steps: #12141 (comment)

AI disclosure: issues found via AI-assisted code review; the fixes and this description were drafted with AI assistance (Claude Code) and reviewed by me.

Trac ticket: https://core.trac.wordpress.org/ticket/64605

[github-actions]

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.

Core Committers: Use this line as a base for the props when committing in SVN:

Props jorgefilipecosta, gziolo, justlevine.

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

[github-actions]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

[justlevine]

@jorgefilipecosta can you link this to the trac ticket please? I don't have edit perms in this repo.
https://core.trac.wordpress.org/ticket/64605

[jorgefilipecosta]

@jorgefilipecosta can you link this to the trac ticket please? I don't have edit perms in this repo. core.trac.wordpress.org/ticket/64605

Nice catch the ticket mention was added.

[gziolo]

Let's run development, review, and testing through WordPress/ai#691, then sync all agreed refinements here.

[gziolo]

I left my feedback.

Two questions regarding core/get-site-info:

• It covers some similar settings but is scoped to the site. Should it also respect the show_in_abilities check wherever applicable?
• Should it get the default value in the schema aligned to (object) array() as here?

[gziolo]

I noticed that Core settings get registered on the rest_api_init hook:

add_action( 'rest_api_init', 'register_initial_settings', 10 );

It's worth double-checking whether there won't be a race condition with wp_abilities_api_init.

The long-term question is whether get_exposed_settings() could be computed lazily inside the execute/schema callbacks instead of being cached at registration? That would remove the ordering coupling and match the sibling's live‑compute model.

[jorgefilipecosta]

Good catch on the ordering. wp_abilities_api_init fires lazily and isn't ordered relative to rest_api_init, so register() now calls register_initial_settings() before computing the snapshot whenever rest_api_init hasn't fired (or is mid-fire before priority 10). Added the guard in ae862f0 and documented the timing in 59e1819; re-registering later on rest_api_init is harmless.

On computing it lazily: I kept the snapshot cached at registration on purpose. The input schema, output schema, and execute callback all have to derive from the exact same set of exposed settings, so computing it once avoids walking get_registered_settings() three times per request and any risk of the schema and the output drifting apart. With the ordering handled explicitly there's no coupling left to remove, so I dropped the unreachable recompute branch in 13f4d31.

[jorgefilipecosta]

Following your later suggestion, core settings are now registered on wp_abilities_api_init, so the ability does not handle this anymore 👍

[jorgefilipecosta]

I left my feedback.

Two questions regarding core/get-site-info:

• It covers some similar settings but is scoped to the site. Should it also respect the show_in_abilities check wherever applicable?

• Should it get the default value in the schema aligned to (object) array() as here?

Hi @gziolo I think the answer is yes to both, but I would prefer to do that in a separate PR to avoid this one being too huge.

[jorgefilipecosta]

All the reviews comments were applied this is ready for another look.

[gziolo]

One bad setting value fails the whole core/read-settings call

A behavior question to seal with a test.

execute() validates the full output against the schema, so one stored value that does not match its schema makes the entire call return a WP_Error. The client then reads none of the settings.

This is reachable. default_ping_status and default_comment_status use an open|closed enum, and their stored value can drift outside it (direct update_option(), imports, old data). sanitize_option() only maps '0' and '' to 'closed', so a value like 'not-a-valid-status' sticks. admin_email (format: email) is a second, lower chance trigger.

Commit 714d164 handled this by validating and sanitizing each value against its schema (like WP_REST_Settings_Controller::prepare_value()) and dropping only the bad one. The sync commit a6167bf swapped it back to cast_value() to match the AI plugin, which brought the problem back.

A test that pins it down:

public function test_core_read_settings_drops_values_that_fail_their_schema(): void {
	$this->become_admin();

	// sanitize_option() only coerces '0' and '' to 'closed', so this out-of-enum value sticks.
	update_option( 'default_ping_status', 'not-a-valid-status' );

	$result = wp_get_ability( 'core/read-settings' )->execute( array() );

	$this->assertNotWPError( $result, 'One bad value must not fail the whole ability.' );
	$this->assertArrayHasKey( 'blogname', $result );               // others still returned
	$this->assertArrayNotHasKey( 'default_ping_status', $result ); // only the bad one dropped
}

On this branch it fails:

Ability "core/read-settings" has invalid output. Reason: output[default_ping_status] is not one of open and closed.

With the 714d164 approach restored, it passes.

Decision: what should happen for a value that does not match its schema?

• A (my preference): drop that value and return the rest. The test above encodes this.
• B: keep the cast and accept the whole call failing. If so, let's add a test that documents this on purpose.

The plugin class mirrors the core class, so the same choice should land there too. Happy to help with the plugin side.

---

Side question (independent from the above): the sibling abilities core/get-site-info, core/get-user-info, and core/get-environment-info still use 'default' => array() for their input schema, while core/read-settings uses 'default' => (object) array(). So an empty type: object default serializes as [] for them and {} here. Worth aligning them to (object) array() too? It does not depend on the decision above, so maybe it is cleaner as its own small commit.

[gziolo]

Consider wiring register_initial_settings on wp_abilities_api_init too

The ability builds its schema from the registered settings at registration time, so those settings must exist when wp_abilities_api_init fires. Today register_initial_settings is only hooked to rest_api_init, and that action fires lazily inside rest_get_server() when the REST server is first built. On cron, WP-CLI, or any direct ability call that never builds the REST server, the settings are not registered yet. That is why register() calls register_initial_settings() itself with the did_action/doing_action guard.

It works, but it makes the ability responsible for core's bootstrap ordering. A cleaner shape could be to treat the settings as a shared dependency and wire them into both subsystems that use them:

add_action( 'rest_api_init',         'register_initial_settings', 10 );
add_action( 'wp_abilities_api_init', 'register_initial_settings', 1 ); // before core abilities (priority 10)

To make this safe to run from more than one hook, register_initial_settings() could get a small internal check that returns early when the core settings are already registered. register_setting() appends to $new_allowed_options on every call, so without such a guard a second run duplicates those entries and re-fires the register_setting action. The check should look at the actual registration state (for example whether a known core setting like blogname is present) rather than a static flag, so it stays correct when the registry is reset, as the tests do.

With that in place the settings register once and correctly in both cases, REST and Abilities, and the ability no longer needs its own did_action/doing_action logic.

What do you think? If it sounds good I am happy to help wire it up.

[gziolo]

If there are no settings registered, then there is no need to register the ability as it won't return anything anyway.

[jorgefilipecosta]

The ability is now not registered when no setting is exposed 👍

[gziolo]

Nitpick, here and in other open PRs, it might make more sense to follow naming conventions from other places and use WP_Abilities_ prefix and follow with class-wp-abilities- as file name. This would better mirror how it would look when using namespaces: WordPress/Abilities/Settings.

[jorgefilipecosta]

Renamed to WP_Abilities_Settings 👍

[gziolo]

Thanks @jorgefilipecosta! Nice work on this. The port is faithful to the plugin, the option.php change is clean and well-documented, and CI is green. We are nearly there.

The remaining points are the ones I raised above. The main one is the bad-value handling, since it needs an actual fix here and in the plugin so they stay in sync. The rest are shared conventions and small polish: the WP_Abilities_ class naming (across the abilities PRs) and the empty-object input default (across the sibling abilities). Once the bad-value case is settled, this is good to go from my side.

[gziolo]

jorgefilipecosta#91 – we should consider offering a solid strategy around settings registration that is predictable not only for WP core registered settings but also for those coming from plugins. I propsed we enforce that enabling show_in_abilities warns when setting gets registered after init making it clear when to register the setting.

[gziolo]

I pushed 749c2eb with two changes.

1. The ability is now public.

core/settings-get now sets 'public' => true, like the other core abilities. This carries over WordPress/ai#1122. In core, public also enables show_in_rest, so the old flag is no longer needed.

2. show_in_abilities => true reuses the REST API setup.

When show_in_abilities is true, the setting now uses the same name and schema as in show_in_rest. When it is an array, it is used as is.

Because of this, all core settings now use only 'show_in_abilities' => true. We no longer repeat the email format or the open|closed enum. The names now match /wp/v2/settings:

Option	Ability name
blogname	title
blogdescription	description
siteurl	url
admin_email	email
timezone_string	timezone
WPLANG	language
wp_page_for_privacy_policy	page_for_privacy_policy

The other settings already had the same name in both APIs.

One small side effect: siteurl now also gets the uri format from REST. If the stored value is not a valid URI, the ability leaves it out, like the REST API does.

New tests check that the names match the REST API, and that an array in show_in_abilities replaces the REST arguments.

Two follow-ups:

• The PR description and the manual test comment still use the old names, like blogname.
• The AI plugin still uses the old names, so it needs a similar change.