WP_Theme_JSON: deprecate to_ruleset() and replace with Style Engine compile_css()#73117
Closed
ramonjd wants to merge 7 commits into
Closed
WP_Theme_JSON: deprecate to_ruleset() and replace with Style Engine compile_css()#73117ramonjd wants to merge 7 commits into
ramonjd wants to merge 7 commits into
Conversation
ramonjd
requested review from
spacedmonkey and
tellthemachines
as code owners
November 9, 2025 01:23
ramonjd
added
Global Styles
ramonjd
changed the title
|
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 If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
ramonjd
force-pushed
the
migrate/theme-json-to_ruleset-to-style-engine
branch
2 times, most recently
from
November 9, 2025 01:34
7ee9bcf to
b158b1c
Compare
|
Size Change: 0 B Total Size: 2.47 MB ℹ️ View Unchanged
|
ramonjd
commented
Nov 9, 2025
| @@ -28,7 +28,7 @@ class WP_Theme_JSON_Gutenberg_Test extends WP_UnitTestCase { | |||
| * | |||
Member
Author
There was a problem hiding this comment.
All the changes in this file are whitespace changes between property and value in CSS declarations.
The Style Engine outputs rules without whitespace, e.g., font-size:60px;, whereas the theme json class outputs font-size: 60px;
ramonjd
commented
Nov 9, 2025
ramonjd
commented
Nov 9, 2025
ramonjd
commented
Nov 9, 2025
| if ( empty( $declarations ) ) { | ||
| return ''; | ||
| } | ||
| _deprecated_function( __METHOD__, 'Gutenberg 7.0.0', 'WP_Style_Engine_Gutenberg::compile_css()' ); |
Member
Author
There was a problem hiding this comment.
In Core, this will be WP_Style_Engine::compile_css()
Contributor
There was a problem hiding this comment.
This is a protected method, does it need a _deprecated_function call, or can it just be removed? I don't see any calls to it in wordpress-develop other than internal calls within the Theme JSON class.
Or is it to protect classes (like this one in Gutenberg) that might be extending the Theme JSON class? If so, then yes, deprecating sounds safer! (Did I just answer my own question? 😆)
Member
Author
There was a problem hiding this comment.
It's a good question. I'd actually be happy to delete it.
But I did it for the reason you mention (in case it's been extended) and this is despite the 4yo notice at the top of the class that says
/**
* Class that encapsulates the processing of structures that adhere to the theme.json spec.
*
* This class is for internal core usage and is not supposed to be used by extenders (plugins and/or themes).
* This is a low-level API that may need to do breaking changes. Please,
* use get_global_settings, get_global_styles, and get_global_stylesheet instead.
*
* @access private
*/So do we care about folks who extended anyway? 🤔
youknowriad
reviewed
Nov 9, 2025
…son compatibility - Updated `compile_css` method to utilize `WP_Style_Engine_Utils` for normalizing CSS declarations from theme.json format. - Added new utility class `WP_Style_Engine_Utils` with methods for converting theme.json declarations to associative array format. - Included tests for the new utility functions to ensure proper conversion and handling of various input formats. - Updated relevant files to reflect changes in CSS compilation logic. This refactor enhances the flexibility of the style engine by supporting both associative array and theme.json formats for CSS declarations.
- Replaced static::to_ruleset calls with WP_Style_Engine_Gutenberg::compile_css for improved CSS generation. - Updated various sections to ensure consistent handling of CSS declarations and selectors. - Adjusted test cases to reflect changes in CSS output formatting. This refactor enhances the maintainability and performance of the CSS compilation process within the theme JSON handling.
- Marked the static::to_ruleset method as deprecated in favor of WP_Style_Engine_Gutenberg::compile_css for improved CSS handling. - Updated the method to delegate CSS compilation to the new style engine, ensuring better format detection and conversion. This change enhances the maintainability of the code by consolidating CSS generation logic.
…Functionality - Deleted the WP_Style_Engine_Utils class and its associated methods for normalizing CSS declarations. - Integrated the normalization logic directly into the WP_Style_Engine class, enhancing encapsulation and reducing dependencies. - Updated references in the load.php and package.json files to reflect the removal of the utility class. - Adjusted tests to ensure compatibility with the new structure. This refactor streamlines the codebase by consolidating functionality and improving maintainability.
ramonjd
force-pushed
the
migrate/theme-json-to_ruleset-to-style-engine
branch
from
March 11, 2026 05:21
b259969 to
8f7e507
Compare
|
Flaky tests detected in 51016f3. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/22944292665
|
Member
Author
|
This change is premature.
Now we could accommodate this in the style engine and skip using the filter for theme JSON operations, or add the missing properties via I think we need to modernize the CSS validation/sanitization through some API like the HTML processor. |
…handle simple number values
Member
Author
|
Just reopened to add required changes to get things to pass. Now closing again 😄 I'll come back with a plan. |
ramonjd
commented
Mar 11, 2026
| foreach ( $spacing_rule['rules'] as $css_property => $css_value ) { | ||
| $current_css_value = is_string( $css_value ) ? $css_value : $block_gap_value; | ||
| if ( static::is_safe_css_declaration( $css_property, $current_css_value ) ) { | ||
| // Iterate over each of the styling rules and substitute non-string values such as `null` with the real `blockGap` value. |
Member
Author
There was a problem hiding this comment.
Trunk uses to_ruleset — which builds CSS via string concatenation ($dec['name'] . ': ' . $dec['value'])`.
When $dec['value'] is bool(true), PHP's implicit coercion converts it to '1' and produces margin-block-start: 1. That's why trunk tests pass without any fix.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Context
Part of #65728
This will be a series of small, and probably very infrequent PRs to move styles-related logic from
WP_Theme_JSONto the style engine.There's a rough plan over at the issue. The strategy is to knock things off one by one with the end goal being that the style engine can generated CSS from a theme.json tree.
What
Deprecates
WP_Theme_JSON_Gutenberg::to_ruleset()and replaces all internal calls withWP_Style_Engine_Gutenberg::compile_css().Why
This is the first phase of extracting style/CSS logic from
WP_Theme_JSONinto the Style Engine (see #65728). Theto_ruleset()method duplicates functionality already present in the Style Engine, and consolidating CSS generation improves maintainability and reduces code duplication.How
**Added private methods
normalize_declarations()andconvert_theme_json_declarations()to handle format conversion between theme.json's array-of-arrays format and the Style Engine's associative array format.Enhanced
WP_Style_Engine::compile_css()to auto-detect and convert theme.json format declarations using the new utility class.Replaced all 9 internal calls to
to_ruleset()withWP_Style_Engine_Gutenberg::compile_css()throughoutWP_Theme_JSON_Gutenberg.Deprecated
to_ruleset()method with@deprecatedtag and_deprecated_function()call, keeping it as a backwards-compatible wrapper that delegates to the Style Engine.Updated test expectations to match Style Engine's CSS output format (no spaces after colons in declarations).
Testing instructions
npm run test:unit:php:base -- --filter WP_Theme_JSON_Gutenberg_Testnpm run test:unit:php:base -- --filter WP_Style_Engineto_ruleset()method should trigger a deprecation notice if called directly (though all internal calls have been replaced).WP_Style_Engine_Gutenberg::compile_css()as the alternative..has-*-color,.has-*-font-size, etc.) work as expected.