Make global styles data filterable

[oandregal]

What?

This PR tries making the different layers of global styles data filterable.

Why?

Some use cases become a lot easier to do:

• Some themes may want to provide settings dynamically. For example, color presets depending on some contextual information.
• Allow plugins to modify the existing data. For example, provide defaults for many blocks at once. See Allow plugins to include a theme.json file in the same way themes do #41707
• Some agencies may want to edit or remove core data (color presets, etc).

How?

By creating a filter for each data layer of Global Styles that 3rd parties can use:

• global_styles_default => to filter data provided by core
• global_styles_blocks => to filter data provided by the blocks (only styles so far)
• global_styles_theme => to filter data provided by the theme
• global_styles_user => to filter data provided by the user

Prior work

There were previous attempts to add filters to global styles that didn't make the cut for different reasons.

• Filters to modify the stylesheet and the low-level schema Allow filtering for global styles #25499 by @aristath
• Filter the stylesheet and theme support data Add global styles PHP filters #27509 by @aristath
• Filters to modify the low-level schema Add hooks to modify theme.json structure #27722 by @oandregal
• Filter the stylesheet generated by global styles Add a "global_styles" filter #28687 by @aristath
• Make the theme's theme.json extensible Global Styles: Make theme.json extensible #30259 by @scruffian
• Filters to shortcircuit the public API (wp_get_global_* functions) Add filters to shortcircuit the public API of global styles #36909 by @oandregal

Testing Instructions

Use the filters to modify some of the data. For example, this is how the theme data can be modified:

<?php

function filter_global_styles_theme( $theme_json ){
        $new_data = array(
                'version'  => 2,
                'settings' => array(
                        'color' => array(
                                'text'  => false, /* disable text color UI */
                                'palette'    => array( /* New palette */
                                        array(
                                                'slug'  => 'foreground',
                                                'color' => 'red',
                                                'name'  => 'Foreground',
                                        ),
                                ),
                        ),
                ),
        );
        return $theme_json->update_with( $new_data );
}
add_filter( 'global_styles_theme', 'filter_global_styles_theme' );

TODO / Follow-ups

• How to make set_spacing_sizes filterable as well. See https://github.com/WordPress/gutenberg/pull/41527/files#r966773252
• The changes for the resolver live in lib/experimental though some are expected to be ported to 6.1. The changes that affect this PR have been ported.

[aristath]

YES!!
I've tried adding filters multiple times but it was too soon for those PRs. I think now we're at a point in time where we can do this with confidence.
I only had one note for this PR, and this is the addition of a global_styles_user filter 👍

[oandregal]

Just in the line below there's set_spacing_sizes, a configuration for spacing presets that does not follow the normal algorith (core > theme > user), so it wouldn't be filterable. I need to figure out how that works and whether it can work like any other theme.json setting. See https://github.com/WordPress/gutenberg/pull/41527/files#r966773252

[oandregal]

With the current proposal, this is what a theme should do to provide dynamic values:

<?php

function filter_global_styles_theme( $theme_json ){
	$dynamic_data = array(
		'version'  => 2,
		'settings' => array(
			'color' => array(
				'text'       => false, /* New setting */
				'palette'    => array( /* New palette */
					array(
						'slug'  => 'foreground',
						'color' => 'red',
						'name'  => 'Foreground',
					),
					array(
						'slug'  => 'New foreground',
						'color' => 'hotpink',
						'name'  => 'New foreground',
					),
				),
			),
		),
	);

	$theme_json->merge( new WP_Theme_JSON( $dynamic_data, 'theme' ) );
	return $theme_json;
}
add_filter( 'global_styles_theme', 'filter_global_styles_theme' );

A few things here:

• The author needs to provide a version. I think we should maintain this requirement, to prevent people using this hook from having to update when there's a new theme.json version (changes to shape, etc). We already provide migrations at runtime for this, so we should use them here as well.
• The ergonomics can be improved. We still need to make sure this data goes through the following processes: migration, validation, origin management, merging. In this example I use WP_Theme_JSON class, which has been kept private so far. I think we can provide a different public API that complements the existing.

[oandregal]

Pushed a few changes, and now consumers can use the new gutenberg_merge_theme_json to do the heavy lifting for them:

(edit: pushed 5d3b638 so $origin is optional in gutenberg_merge_theme_json):

<?php

function filter_global_styles_theme( $existing ){
	$dynamic_data = array(
		'version'  => 2,
		'settings' => array(
			'color' => array(
				'text'       => false, /* New setting */
				'palette'    => array( /* New palette */
					array(
						'slug'  => 'foreground',
						'color' => 'red',
						'name'  => 'Foreground',
					),
					array(
						'slug'  => 'New foreground',
						'color' => 'hotpink',
						'name'  => 'New foreground',
					),
				),
			),
		),
	);
	$filtered = gutenberg_merge_theme_json( $existing, $dynamic_data );

	return $filtered;
}
add_filter( 'global_styles_theme', 'filter_global_styles_theme' );

[oandregal]

By filling the $origin depending on which filter is running, we avoid asking consumers to do it themselves. Though if the consumer does provide it, we use it instead.

[nerrad]

I like this. It abstracts away this requirement which might not be easily understood by consumers implementing the filter.

[mtias]

As mentioned in Slack, absolutely in favor of adding this. Low level hooks at all the levels in which we construct global style objects is necessary and should provide flexibility for plugins and sites to do a lot of creative things.

[nerrad]

I think the direction of this is good. I do wonder if there should be some validation of returned filter values. While I appreciate the availability of gutenberg_merge_them_json to handle merging, it's not something intuitive for consumers to implement on whatever they are merging into existing objects. There's also increased fragility. I wonder if it'd be better to pass through an instance of a WP_Theme_JSON object and consumers would be expected to use the merge method and then return an instance of WP_Theme_JSON (which could be validated).

So for instance the theme filter would be something like this:

<?php
$unfiltered_json_data = new WP_Theme_JSON_Gutenberg( $theme_json_data );
try {
  $theme_json_data = apply_filters( 'global_styles_theme', $unfiltered_json_data );
  if ( ! $theme_json_data instanceof WP_Theme_JSON ) {
    throw new Exception( 'Incorrect usage of filter' );
  }
} catch (Exception $e) {
  // just handling incorrect usage of filter and resetting to unfiltered data
  $theme_json_data = $unfiltered_json_data;
}

static::$theme   = $theme_json_data;

And implementation would be:

function filter_global_styles_theme( WP_Theme_JSON $theme_json ){
	$dynamic_data = array(
		'version'  => 2,
		'settings' => array(
			'color' => array(
				'text'       => false, /* New setting */
				'palette'    => array( /* New palette */
					array(
						'slug'  => 'foreground',
						'color' => 'red',
						'name'  => 'Foreground',
					),
					array(
						'slug'  => 'New foreground',
						'color' => 'hotpink',
						'name'  => 'New foreground',
					),
				),
			),
		),
	);

  /**
   * This would be a new method on WP_Theme_JSON for merging in raw data.
   * It internally handles converting the dynamic data to a WP_Theme_JSON object
   * and the consumer would not need to provide $origin.
   */
	$theme_json->merge_raw( $dynamic_data );
	return $theme_json;
}
add_filter( 'global_styles_theme', 'filter_global_styles_theme' );

I think this goes a bit back towards your original solution with the change of implementing a new method on WP_Theme_JSON for handling merging raw data.

[nerrad]

I like this. It abstracts away this requirement which might not be easily understood by consumers implementing the filter.

[oandregal]

I think the direction of this is good. I do wonder if there should be some validation of returned filter values.

The returned values will be validated in the same way a theme.json provided by the theme is. Note that after the filters, the next call is WP_Theme_JSON( $filtered_data ).

[oandregal]

I wonder if it'd be better to pass through an instance of a WP_Theme_JSON object and consumers would be expected to use the merge method and then return an instance of WP_Theme_JSON (which could be validated).

Having tested both approaches, using a simple array is more familiar and ergonomic for consumers: it's a construct people know how to work with in the language, and it mimics the mechanics of array_merge but it's tailored to theme.json data.

At first sight, the two different approaches may look similar:

$existing->merge_raw( $new_data );

vs

gutenberg_merge_theme_json( $existing, $new_data );

Though the 1st approach forces us to making WP_Theme_JSON public (exposing a lot of unnecessary complexity to consumers) and it's more inflexible (we can't get rid of the class in the future, should we want).

[andrewserong]

Apologies for commenting just after this PR merged, but should this line have a Gutenberg suffix, or have a class_exists check before defining it, so that we don't run into any issues when this is backported to core?

[gziolo]

Yes, it'd be best to call class_exists before requiring this file.

[aristath]

+1

[aristath]

@aristath I know you already approved when this PR was merely a draft and not fully working/developed. I'd welcome a technical review now if you've got time.

I'm a bit late since this was already merged, but I'll leave my feedback anyway; this implementation makes sense and looks good to me 👍
Thank you!

[gziolo]

Great job bringing this to the finish line @oandregal. The way you implemented it is even better than what I initially drafted in #44015 (comment), as the new class might be applicable in different contexts, too. It might seem like overhead adding a wrapper class at first glance, but it also gives you space for future optimizations as you have control over the input and output value of the filter.

As a follow-up, we need to document all new filters inline in the codebase like:

https://github.com/WordPress/wordpress-develop/blob/1746a68584dbadb8807a1520546725f8a1e572df/src/wp-includes/class-wp-block-type.php#L381-L389

This is going to be necessary when backporting to WordPress core.

In addition to that, we could extend documentation in the block editor handbook. It might even be worth adding a new document specific to themes in:

https://github.com/WordPress/gutenberg/tree/trunk/docs/reference-guides/filters

[gziolo]

With WP filters we need to return the same data type as in the input, so that should be $data instead of config, so maybe the following would be more accurate:

$data = apply_filters( 'global_styles_default', new WP_Theme_JSON_Data( $config, 'default' ) );
static::$core = new WP_Theme_JSON_Gutenberg( $data->get_config(), 'default' );

I see the same pattern in other places. WP_Theme_JSON lists $theme_json in the constructor:

https://github.com/WordPress/wordpress-develop/blob/1746a68584dbadb8807a1520546725f8a1e572df/src/wp-includes/class-wp-theme-json.php#L431-L440

Maybe, we could rename that to $theme_config in WP core and here it would be $data->get_theme_config()?

[oandregal]

@nerrad @andrewserong @gziolo Addressed your feedback at #44109

[oandregal]

#44111 documents the new filters in the block editor handbook

[fabiankaegy]

I've added the Needs Dev Note label here because I think this should get a dev note for the 6.1 release.

CC: @bph

[oandregal]

The devnote content can actually be the same as the documentation. It can work either as a standalone note or as part of a larger one. Would we publish a consolidated devnote for all global styles work in WordPress 6.1? (I've been out a few months in this cycle and don't have a good context of what has changed).

[oandregal]

#44159 proposes we rename the filters from global_styles_* to theme_json_*.

[oandregal]

This is being backported as part of WordPress/wordpress-develop#3247

[bph]

Would we publish a consolidated devnote for all global styles work in WordPress 6.1

@oandregal Yes, I think you should. I am working through collected all the PRs but I am uncertain whether I get them all. 😸

[adamziel]

I like how this PR opens the door for updating the global styles in plugins without introducing new core APIs.

That being said, I’m a bit worried, too. Imagine 5 different plugins competing to update similar config values. I can't think of a clean way of solving it, but if this was a declarative API then it could at least run some checks and notify developers about, say, conflicting updates.

Perhaps I’m thinking of theme.json dev tools with a traceable cascade of values, like what Chrome has for CSS. That's a long way to go, though. Perhaps introducing a filter today is for the best after all. Implementing it as $theme_json->update_with( $new_data ); is perfect because it makes the source of the changes traceable.