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

* 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

View File

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

View File

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

View File

@ -13,7 +13,7 @@
* *
* @global string $wp_version * @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. * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.