vhad/wordpress-develop
1
0
Fork 0
mirror of https://github.com/gosticks/wordpress-develop.git synced 2026-06-28 22:30:04 +00:00
Code Issues Actions Packages 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.

git-svn-id: https://develop.svn.wordpress.org/trunk@50967 602fd350-edb4-49c9-b593-d223f7449a82
This commit is contained in:
Sergey Biryukov
2021-05-24 13:24:05 +00:00
parent 23e669465a
commit e4947e935d
5 changed files with 153 additions and 113 deletions
Download Patch File Download Diff File Expand all files Collapse all files

153
src/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;
}
}