Upstream/WordPress
1
0
Fork 0
mirror of https://github.com/WordPress/WordPress.git synced 2024-11-10 12:50:18 +01:00
Code Issues Projects Releases Wiki Activity

Docs: Some documentation and test improvements for WP_Theme_JSON and WP_Theme_JSON_Resolver classes:

Browse Source 
* Add missing `@since` tags.
* Update some DocBlocks per the documentation standards.
* Rename test files and classes per the naming conventions.
* Fix some code alignment issues reported by WPCS.

Follow-up to [50959], [50960].

See #52991, #53175.
Built from https://develop.svn.wordpress.org/trunk@50967


git-svn-id: http://core.svn.wordpress.org/trunk@50576 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Sergey Biryukov 2021-05-24 13:25:56 +00:00
parent 645fffca13
commit 19ea4bd412
3 changed files with 139 additions and 110 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

153
wp-includes/class-wp-theme-json-resolver.php
View File

@ -1,14 +1,15 @@
<?php
/**
* Process the different data sources for site-level
* config and offers and API to work with them.
* WP_Theme_JSON_Resolver class
*
* @package WordPress
* @subpackage Theme
* @since 5.8.0
*/
/**
* Class that abstracts the processing
* of the different data sources.
* Class that abstracts the processing of the different data sources
* for site-level config and offers an API to work with them.
*
* @access private
*/
@ -17,6 +18,7 @@ class WP_Theme_JSON_Resolver {
/**
* Container for data coming from core.
*
* @since 5.8.0
* @var WP_Theme_JSON
*/
private static $core = null;
@ -24,6 +26,7 @@ class WP_Theme_JSON_Resolver {
/**
* Container for data coming from the theme.
*
* @since 5.8.0
* @var WP_Theme_JSON
*/
private static $theme = null;
@ -31,24 +34,26 @@ class WP_Theme_JSON_Resolver {
/**
* Whether or not the theme supports theme.json.
*
* @var boolean
* @since 5.8.0
* @var bool
*/
private static $theme_has_support = null;
/**
* Structure to hold i18n metadata.
*
* @var Array
* @since 5.8.0
* @var array
*/
private static $theme_json_i18n = null;
/**
* Processes a file that adheres to the theme.json
* schema and returns an array with its contents,
* or a void array if none found.
* Processes a file that adheres to the theme.json schema
* and returns an array with its contents, or a void array if none found.
*
* @since 5.8.0
*
* @param string $file_path Path to file. Empty if no file.
*
* @return array Contents that adhere to the theme.json schema.
*/
private static function read_json_file( $file_path ) {
@ -78,35 +83,36 @@ class WP_Theme_JSON_Resolver {
*
* For example, given this input:
*
* {
* "settings": {
* "*": {
* "typography": {
* "fontSizes": [ { "name": "Font size name" } ],
* "fontStyles": [ { "name": "Font size name" } ]
* {
* "settings": {
* "*": {
* "typography": {
* "fontSizes": [ { "name": "Font size name" } ],
* "fontStyles": [ { "name": "Font size name" } ]
* }
* }
* }
* }
* }
* }
*
* will return this output:
*
* [
* 0 => [
* 'path' => [ 'settings', '*', 'typography', 'fontSizes' ],
* 'key' => 'name',
* 'context' => 'Font size name'
* ],
* 1 => [
* 'path' => [ 'settings', '*', 'typography', 'fontStyles' ],
* 'key' => 'name',
* 'context' => 'Font style name'
* ]
* ]
* [
* 0 => [
* 'path' => [ 'settings', '*', 'typography', 'fontSizes' ],
* 'key' => 'name',
* 'context' => 'Font size name'
* ],
* 1 => [
* 'path' => [ 'settings', '*', 'typography', 'fontStyles' ],
* 'key' => 'name',
* 'context' => 'Font style name'
* ]
* ]
*
* @since 5.8.0
*
* @param array $i18n_partial A tree that follows the format of i18n-theme.json.
* @param array $current_path Keeps track of the path as we walk down the given tree.
*
* @return array A linear array containing the paths to translate.
*/
private static function extract_paths_to_translate( $i18n_partial, $current_path = array() ) {
@ -134,7 +140,9 @@ class WP_Theme_JSON_Resolver {
/**
* Returns a data structure used in theme.json translation.
*
* @return array An array of theme.json fields that are translatable and the keys that are translatable
* @since 5.8.0
*
* @return array An array of theme.json fields that are translatable and the keys that are translatable.
*/
public static function get_fields_to_translate() {
if ( null === self::$theme_json_i18n ) {
@ -147,11 +155,12 @@ class WP_Theme_JSON_Resolver {
/**
* Translates a chunk of the loaded theme.json structure.
*
* @since 5.8.0
*
* @param array $array_to_translate The chunk of theme.json to translate.
* @param string $key The key of the field that contains the string to translate.
* @param string $context The context to apply in the translation call.
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
*
* @return array Returns the modified $theme_json chunk.
*/
private static function translate_theme_json_chunk( array $array_to_translate, $key, $context, $domain ) {
@ -168,14 +177,14 @@ class WP_Theme_JSON_Resolver {
}
/**
* Given a theme.json structure modifies it in place
* to update certain values by its translated strings
* according to the language set by the user.
* Given a theme.json structure modifies it in place to update certain values
* by its translated strings according to the language set by the user.
*
* @since 5.8.0
*
* @param array $theme_json The theme.json to translate.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
*
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return array Returns the modified $theme_json_structure.
*/
private static function translate( $theme_json, $domain = 'default' ) {
@ -228,6 +237,8 @@ class WP_Theme_JSON_Resolver {
/**
* Return core's origin config.
*
* @since 5.8.0
*
* @return WP_Theme_JSON Entity that holds core data.
*/
public static function get_core_data() {
@ -245,16 +256,16 @@ class WP_Theme_JSON_Resolver {
/**
* Returns the theme's data.
*
* Data from theme.json can be augmented via the
* $theme_support_data variable. This is useful, for example,
* to backfill the gaps in theme.json that a theme has declared
* via add_theme_supports.
* Data from theme.json can be augmented via the $theme_support_data variable.
* This is useful, for example, to backfill the gaps in theme.json that a theme
* has declared via add_theme_supports.
*
* Note that if the same data is present in theme.json
* and in $theme_support_data, the theme.json's is not overwritten.
* Note that if the same data is present in theme.json and in $theme_support_data,
* the theme.json's is not overwritten.
*
* @since 5.8.0
*
* @param array $theme_support_data Theme support data in theme.json format.
*
* @return WP_Theme_JSON Entity that holds theme data.
*/
public static function get_theme_data( $theme_support_data = array() ) {
@ -279,22 +290,19 @@ class WP_Theme_JSON_Resolver {
}
/**
* There are different sources of data for a site:
* core and theme.
* There are different sources of data for a site: core and theme.
*
* While the getters {@link get_core_data},
* {@link get_theme_data} return the raw data
* from the respective origins, this method merges them
* all together.
* While the getters {@link get_core_data}, {@link get_theme_data} return the raw data
* from the respective origins, this method merges them all together.
*
* If the same piece of data is declared in different origins (core and theme),
* the last origin overrides the previous. For example,
* if core disables custom colors but a theme enables them,
* the theme config wins.
* the last origin overrides the previous. For example, if core disables custom colors
* but a theme enables them, the theme config wins.
*
* @since 5.8.0
*
* @param array $settings Existing block editor settings.
* Empty array by default.
*
* @return WP_Theme_JSON
*/
public static function get_merged_data( $settings = array() ) {
@ -321,24 +329,23 @@ class WP_Theme_JSON_Resolver {
}
/**
* Builds the path to the given file
* and checks that it is readable.
* Builds the path to the given file and checks that it is readable.
*
* If it isn't, returns an empty string,
* otherwise returns the whole file path.
* If it isn't, returns an empty string, otherwise returns the whole file path.
*
* @since 5.8.0
*
* @param string $file_name Name of the file.
* @return string The whole file path or empty if the file doesn't exist.
*/
private static function get_file_path_from_theme( $file_name ) {
// This used to be a locate_template call.
// However, that method proved problematic
// due to its use of constants (STYLESHEETPATH)
// that threw errors in some scenarios.
//
// When the theme.json merge algorithm properly supports
// child themes, this should also fallback
// to the template path, as locate_template did.
/*
* This used to be a locate_template call. However, that method proved problematic
* due to its use of constants (STYLESHEETPATH) that threw errors in some scenarios.
*
* When the theme.json merge algorithm properly supports child themes,
* this should also fall back to the template path, as locate_template did.
*/
$located = '';
$candidate = get_stylesheet_directory() . '/' . $file_name;
if ( is_readable( $candidate ) ) {
@ -349,12 +356,14 @@ class WP_Theme_JSON_Resolver {
/**
* Cleans the cached data so it can be recalculated.
*
* @since 5.8.0
*/
public static function clean_cached_data() {
self::$core = null;
self::$theme = null;
self::$theme_has_support = null;
self::$theme_json_i18n = null;
self::$core = null;
self::$theme = null;
self::$theme_has_support = null;
self::$theme_json_i18n = null;
}
}

94
wp-includes/class-wp-theme-json.php
View File

@ -1,13 +1,14 @@
<?php
/**
* Process of structures that adhere to the theme.json schema.
* WP_Theme_JSON class
*
* @package WordPress
* @subpackage Theme
* @since 5.8.0
*/
/**
* Class that encapsulates the processing of
* structures that adhere to the theme.json spec.
* Class that encapsulates the processing of structures that adhere to the theme.json spec.
*
* @access private
*/
@ -16,6 +17,7 @@ class WP_Theme_JSON {
/**
* Container of data in theme.json format.
*
* @since 5.8.0
* @var array
*/
private $theme_json = null;
@ -24,6 +26,7 @@ class WP_Theme_JSON {
* Holds the allowed block names extracted from block.json.
* Shared among all instances so we only process it once.
*
* @since 5.8.0
* @var array
*/
private static $allowed_block_names = null;
@ -62,6 +65,8 @@ class WP_Theme_JSON {
/**
* Constructor.
*
* @since 5.8.0
*
* @param array $theme_json A structure that follows the theme.json schema.
*/
public function __construct( $theme_json = array() ) {
@ -70,12 +75,14 @@ class WP_Theme_JSON {
return;
}
$this->theme_json = self::sanitize( $theme_json );
$this->theme_json = self::sanitize( $theme_json );
}
/**
* Returns the allowed block names.
*
* @since 5.8.0
*
* @return array
*/
private static function get_allowed_block_names() {
@ -91,8 +98,9 @@ class WP_Theme_JSON {
/**
* Sanitizes the input according to the schemas.
*
* @param array $input Structure to sanitize.
* @since 5.8.0
*
* @param array $input Structure to sanitize.
* @return array The sanitized output.
*/
private static function sanitize( $input ) {
@ -143,9 +151,10 @@ class WP_Theme_JSON {
*
* It is recursive and modifies the input in-place.
*
* @since 5.8.0
*
* @param array $tree Input to process.
* @param array $schema Schema to adhere to.
*
* @return array Returns the modified $tree.
*/
private static function remove_keys_not_in_schema( $tree, $schema ) {
@ -175,18 +184,20 @@ class WP_Theme_JSON {
*
* Example:
*
* {
* 'root': {
* 'color': {
* 'custom': true
* {
* 'root': {
* 'color': {
* 'custom': true
* }
* },
* 'core/paragraph': {
* 'spacing': {
* 'customPadding': true
* }
* }
* }
* },
* 'core/paragraph': {
* 'spacing': {
* 'customPadding': true
* }
* }
* }
*
* @since 5.8.0
*
* @return array Settings per block.
*/
@ -201,17 +212,18 @@ class WP_Theme_JSON {
/**
* Builds metadata for the setting nodes, which returns in the form of:
*
* [
* [
* 'path' => ['path', 'to', 'some', 'node' ]
* ],
* [
* 'path' => [ 'path', 'to', 'other', 'node' ]
* ],
* ]
* [
* [
* 'path' => ['path', 'to', 'some', 'node' ]
* ],
* [
* 'path' => [ 'path', 'to', 'other', 'node' ]
* ],
* ]
*
* @since 5.8.0
*
* @param array $theme_json The tree to extract setting nodes from.
*
* @return array
*/
private static function get_setting_nodes( $theme_json ) {
@ -242,17 +254,21 @@ class WP_Theme_JSON {
/**
* Merge new incoming data.
*
* @since 5.8.0
*
* @param WP_Theme_JSON $incoming Data to merge.
*/
public function merge( $incoming ) {
$incoming_data = $incoming->get_raw_data();
$this->theme_json = array_replace_recursive( $this->theme_json, $incoming_data );
// The array_replace_recursive algorithm merges at the leaf level.
// For leaf values that are arrays it will use the numeric indexes for replacement.
// In those cases, what we want is to use the incoming value, if it exists.
//
// These are the cases that have array values at the leaf levels.
/*
* The array_replace_recursive algorithm merges at the leaf level.
* For leaf values that are arrays it will use the numeric indexes for replacement.
* In those cases, what we want is to use the incoming value, if it exists.
*
* These are the cases that have array values at the leaf levels.
*/
$properties = array();
$properties[] = array( 'color', 'palette' );
$properties[] = array( 'color', 'gradients' );
@ -277,6 +293,8 @@ class WP_Theme_JSON {
/**
* Returns the raw data.
*
* @since 5.8.0
*
* @return array Raw data.
*/
public function get_raw_data() {
@ -284,12 +302,12 @@ class WP_Theme_JSON {
}
/**
*
* Transforms the given editor settings according the
* add_theme_support format to the theme.json format.
*
* @param array $settings Existing editor settings.
* @since 5.8.0
*
* @param array $settings Existing editor settings.
* @return array Config that adheres to the theme.json schema.
*/
public static function get_from_editor_settings( $settings ) {
@ -364,10 +382,12 @@ class WP_Theme_JSON {
$theme_settings['settings']['typography']['fontSizes'] = $font_sizes;
}
// This allows to make the plugin work with WordPress 5.7 beta
// as well as lower versions. The second check can be removed
// as soon as the minimum WordPress version for the plugin
// is bumped to 5.7.
/*
* This allows to make the plugin work with WordPress 5.8 beta
* as well as lower versions. The second check can be removed
* as soon as the minimum WordPress version for the plugin
* is bumped to 5.8.
*/
if ( isset( $settings['enableCustomSpacing'] ) ) {
if ( ! isset( $theme_settings['settings']['spacing'] ) ) {
$theme_settings['settings']['spacing'] = array();

2
wp-includes/version.php
View File

@ -13,7 +13,7 @@
*
* @global string $wp_version
*/
$wp_version = '5.8-alpha-50966';
$wp_version = '5.8-alpha-50967';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.