WP_Theme_JSON_Gutenberg: preserve valid non-preset settings when KSES filters are active #73452

ramonjd · 2025-11-20T02:35:57Z

Problem

When KSES filters are active (via add_action( 'init', 'kses_init_filters' )), valid non-preset settings in Global Styles are being incorrectly filtered out. Specifically:

lightbox.enabled and lightbox.allowEditing for Image blocks

The issue occurs because remove_insecure_settings() only preserved:

Presets (from PRESETS_METADATA)
Indirect CSS properties (from INDIRECT_PROPERTIES_METADATA)

All other valid settings were being stripped, even though they're defined in VALID_SETTINGS and are safe scalar values or arrays.

Solution

Extended VALID_SETTINGS to also do type validation (as well as schema key validation) for the lightbox settings only (for now).

The idea is that VALID_SETTINGS values will act as type validation for further valid settings.

Testing Instructions

Manual Testing

Enable KSES filters:
```
add_action( 'init', 'kses_init_filters' );
```
Add this to your theme's functions.php or a plugin.
Test Image Block Lightbox Settings:
- Go to Appearance > Editor > Styles
- Navigate to Blocks > Image
- Open the Settings panel
- Toggle the "Enlarge on click" (lightbox) setting
- Save the changes
- Expected: The setting should persist after saving and page reload
- Before fix: The setting would revert after saving
Test Other Valid Settings:
- Try changing other valid settings in Global Styles (e.g., layout settings, spacing settings)
- Save and verify they persist
- Expected: All valid settings should be preserved

Automated Testing

Run the PHPUnit tests:

npm run test:unit:php:base -- --filter WP_Theme_JSON_Gutenberg_Test

andrewserong

Nice, I like this approach and it gives room for adding additional settings further down the track. While there are other boolean values we could add, this addresses the issue with the lightbox which is that there is a user-facing feature that folks should be able to interact with, that currently doesn't work when KSES filters are active.

Whereas for other boolean settings like appearanceTools or useRootPAddingAwareAlignments, there isn't a UI for them, so it isn't as critical that we (yet) support them. But that could be something to look at further down the track.

For now, I'm in favour of going with this approach.

Arguably, it could be possible to extend the VALID_SETTINGS to include types instead of null as a value... but I like the approach you've gone with here of keeping them separate, which ensures that VALID_SETTINGS remains fairly simple, too.

I see this PR is still a draft (and that the Github action is complaining that there isn't a corresponding core PR), but IMO this is a good fix, so I'll give it the ✅ and it's working nicely for me in testing.

andrewserong · 2025-11-20T04:33:26Z

lib/class-wp-theme-json-gutenberg.php

+			// Validate the type.
+			$is_valid_type = false;
+			switch ( $type ) {
+				case 'boolean':
+					$is_valid_type = is_bool( $value );
+					break;
+			}


I like this — it gives room for eventually adding settings that might be string values that need a particular kind of validation, too.

andrewserong · 2025-11-20T04:45:38Z

phpunit/class-wp-theme-json-test.php

+	public function test_safe_settings_paths_should_exist_in_valid_settings() {
+		// Verify all paths in SAFE_SETTINGS exist in VALID_SETTINGS.


Oh, nice, thanks for adding this in! I like that this ensures that SAFE_SETTINGS is always a subset of VALID_SETTINGS 👍

github-actions · 2025-11-20T05:16:13Z

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: ramonjd <[email protected]>
Co-authored-by: andrewserong <[email protected]>
Co-authored-by: mmtr <[email protected]>
Co-authored-by: oandregal <[email protected]>
Co-authored-by: t-hamano <[email protected]>

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

ramonjd · 2025-11-20T05:25:55Z

Thanks for the speedy and thorough review, @andrewserong

Arguably, it could be possible to extend the VALID_SETTINGS to include types instead of null as a value

I nearly went down that track, but baulked as I didn't want to cause more bugs given the way VALID_SETTINGS is being used, and then it wouldn't cater for exceptions.

I wonder if SAFE_SETTINGS should be a private const for now?

andrewserong · 2025-11-20T05:38:14Z

I wonder if SAFE_SETTINGS should be a private const for now?

Good question. I see that none of the other consts in this class are declared as private, so I'd lean toward going with a simple const for consistency, but I don't feel strongly about it.

github-actions · 2025-11-20T06:06:35Z

Flaky tests detected in 459384c.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/19608681254
📝 Reported issues:

[Flaky Test] should reload the next page when the timeout ends #57389 in /test/e2e/specs/interactivity/router-navigate.spec.ts

mmtr

Thank you! This does solve the issue on my tests 🙂

lib/class-wp-theme-json-gutenberg.php

phpunit/class-wp-theme-json-test.php

ramonjd · 2025-11-21T04:02:18Z

@t-hamano is this a candidate for RC as well?

t-hamano · 2025-11-21T11:15:52Z

is this a candidate for RC as well?

@ramonjd If I understand correctly, this issue has been around for quite some time, right? If so, it might be better to wait to ship to the core and aim for a more complete fix for the 7.0 release.

ramonjd · 2025-11-23T08:04:24Z

If I understand correctly, this issue has been around for quite some time, right? If so, it might be better to wait to ship to the core and aim for a more complete fix for the 7.0 release.

Ah okay, I only heard about this bug last week, but you're right. Thanks for tip.

ramonjd · 2025-11-23T10:26:01Z

lib/class-wp-theme-json-gutenberg.php

+			if ( is_array( $schema[ $key ] ) ) {
+				if ( ! is_array( $value ) ) {
+					unset( $tree[ $key ] );
+				} elseif ( wp_is_numeric_array( $value ) ) {


The changes in WordPress/wordpress-develop@d1fafd8 were never backported to Gutenberg.

Just doing this for janitorial purposes and to make sure it doesn't affect these changes (it doesn't).

Removes the custom `WP_Theme_JSON::is_assoc()` method again in favor of the existing `wp_is_numeric_array()` helper function. Props mmaattiiaass, costdev, swissspidy, spacedmonkey. Fixes #60360. git-svn-id: https://develop.svn.wordpress.org/trunk@57751 602fd350-edb4-49c9-b593-d223f7449a82

…n valid settings while excluding presets and indirect properties. Update unit tests to verify preservation of valid block and top-level settings.

…mplementing O(1) lookups for preset and indirect property paths, improving performance during valid settings preservation.

… coalescing operator for improved readability.

… settings and enhance preserve_valid_settings method to validate and preserve safe settings. Add unit test to ensure safe settings are retained during property removal.

…FE_SETTINGS exist within VALID_SETTINGS, ensuring integrity of safe settings during validation.

…cumentation to streamline comments and focus on functionality.

…emoving the now redundant implementation and ensuring safe settings are preserved through direct validation, enhancing code clarity.

… internal use only, and update unit test to ensure removal of unsafe settings during validation.

…gs in the sanitize method, ensuring only valid boolean values are preserved. Update unit tests to verify behavior for boolean and non-boolean values in settings.

…ition to enhance code cleanliness.

ramonjd · 2025-11-24T01:13:21Z

I think this is good to go. I've moved the type validation to the VALID_SETTINGS schema modal, but only for the lightbox for now.

We can slowly add more settings as the need arises.

I'll merge into Gutenberg, and if stable, then do the same for Core.

andrewserong · 2025-11-24T01:21:05Z

We can slowly add more settings as the need arises.

Sounds good, and André gave us some good ideas for how we can support more validation types in the future, too 👍
Thanks for persisting with this!

andrewserong approved these changes Nov 20, 2025

View reviewed changes

ramonjd self-assigned this Nov 20, 2025

ramonjd marked this pull request as ready for review November 20, 2025 05:16

ramonjd requested a review from tellthemachines as a code owner November 20, 2025 05:16

andrewserong added the [Type] Bug An existing feature does not function as intended label Nov 20, 2025

ramonjd added the [Feature] Themes Questions or issues with incorporating or styling blocks in a theme. label Nov 20, 2025

This was referenced Nov 20, 2025

Fix lightbox settings not preserved when KSES filters are active #73161

Closed

WP_Theme_JSON: preserve valid non-preset settings when KSES filters are active WordPress/wordpress-develop#10534

Open

ramonjd requested a review from mmtr November 20, 2025 05:41

mmtr approved these changes Nov 20, 2025

View reviewed changes

oandregal reviewed Nov 20, 2025

View reviewed changes

lib/class-wp-theme-json-gutenberg.php Outdated Show resolved Hide resolved

oandregal reviewed Nov 20, 2025

View reviewed changes

phpunit/class-wp-theme-json-test.php Outdated Show resolved Hide resolved

ramonjd force-pushed the try/theme-json-allow-valid-settings branch 2 times, most recently from 67e0fb1 to 59f898d Compare November 21, 2025 03:11

ramonjd commented Nov 23, 2025

View reviewed changes

ramonjd added 7 commits November 24, 2025 12:10

WP_Theme_JSON_Gutenberg: Add preserve_valid_settings method to retai…

c07751e

…n valid settings while excluding presets and indirect properties. Update unit tests to verify preservation of valid block and top-level settings.

WP_Theme_JSON_Gutenberg: Optimize preserve_valid_settings method by i…

a6ddb7c

…mplementing O(1) lookups for preset and indirect property paths, improving performance during valid settings preservation.

linty

5f80c06

WP_Theme_JSON_Gutenberg: Simplify nested output assignment using null…

b64f08a

… coalescing operator for improved readability.

WP_Theme_JSON_Gutenberg: Introduce SAFE_SETTINGS constant for non-CSS…

f3ee04f

… settings and enhance preserve_valid_settings method to validate and preserve safe settings. Add unit test to ensure safe settings are retained during property removal.

WP_Theme_JSON_Gutenberg: Add unit test to verify that all paths in SA…

8628bf5

…FE_SETTINGS exist within VALID_SETTINGS, ensuring integrity of safe settings during validation.

WP_Theme_JSON_Gutenberg: Remove type definitions for SAFE_SETTINGS do…

8e016e7

…cumentation to streamline comments and focus on functionality.

ramonjd added 6 commits November 24, 2025 12:10

WP_Theme_JSON_Gutenberg: Refactor preserve_valid_settings method by r…

800c5c5

…emoving the now redundant implementation and ensuring safe settings are preserved through direct validation, enhancing code clarity.

core backlog entry

5450963

WP_Theme_JSON_Gutenberg: Change SAFE_SETTINGS constant to private for…

c42498a

… internal use only, and update unit test to ensure removal of unsafe settings during validation.

WP_Theme_JSON_Gutenberg: Implement type validation for boolean settin…

84626de

…gs in the sanitize method, ensuring only valid boolean values are preserved. Update unit tests to verify behavior for boolean and non-boolean values in settings.

WP_Theme_JSON_Gutenberg: Remove unnecessary blank line in class defin…

22e9b43

…ition to enhance code cleanliness.

Backporting changes from WordPress/wordpress-develop@d1fafd8

a461b75

ramonjd force-pushed the try/theme-json-allow-valid-settings branch from 7c74bd1 to a461b75 Compare November 24, 2025 01:11

ramonjd merged commit e74af14 into trunk Nov 24, 2025
36 checks passed

ramonjd deleted the try/theme-json-allow-valid-settings branch November 24, 2025 02:34

github-actions bot added this to the Gutenberg 22.2 milestone Nov 24, 2025

ramonjd mentioned this pull request Nov 26, 2025

WP_Theme_JSON: use self:: for class private static methods #73566

Merged

		public function test_safe_settings_paths_should_exist_in_valid_settings() {
		// Verify all paths in SAFE_SETTINGS exist in VALID_SETTINGS.

WP_Theme_JSON_Gutenberg: preserve valid non-preset settings when KSES filters are active #73452

WP_Theme_JSON_Gutenberg: preserve valid non-preset settings when KSES filters are active #73452

Uh oh!

Conversation

ramonjd commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Solution

Testing Instructions

Manual Testing

Automated Testing

Uh oh!

andrewserong left a comment

Choose a reason for hiding this comment

Uh oh!

andrewserong Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

andrewserong Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ramonjd commented Nov 20, 2025

Uh oh!

andrewserong commented Nov 20, 2025

Uh oh!

github-actions bot commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mmtr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ramonjd commented Nov 21, 2025

Uh oh!

t-hamano commented Nov 21, 2025

Uh oh!

ramonjd commented Nov 23, 2025

Uh oh!

ramonjd Nov 23, 2025

Choose a reason for hiding this comment

Uh oh!

ramonjd commented Nov 24, 2025

Uh oh!

andrewserong commented Nov 24, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

ramonjd commented Nov 20, 2025 •

edited

Loading

github-actions bot commented Nov 20, 2025 •

edited

Loading

github-actions bot commented Nov 20, 2025 •

edited

Loading