diff --git a/src/wp-includes/class-wp-theme-json-resolver.php b/src/wp-includes/class-wp-theme-json-resolver.php index b8bb6ec677..ce11c90aea 100644 --- a/src/wp-includes/class-wp-theme-json-resolver.php +++ b/src/wp-includes/class-wp-theme-json-resolver.php @@ -56,7 +56,7 @@ class WP_Theme_JSON_Resolver { * that holds the user data. * * @since 5.9.0 - * @var integer + * @var int */ private static $user_custom_post_type_id = null; @@ -64,7 +64,7 @@ class WP_Theme_JSON_Resolver { * Container to keep loaded i18n schema for `theme.json`. * * @since 5.8.0 - * @since 5.9.0 Renamed from $theme_json_i18n + * @since 5.9.0 Renamed from `$theme_json_i18n`. * @var array */ private static $i18n_schema = null; @@ -150,13 +150,14 @@ class WP_Theme_JSON_Resolver { * the theme.json takes precendence. * * @since 5.8.0 - * @since 5.9.0 Theme supports have been inlined and the argument removed. + * @since 5.9.0 Theme supports have been inlined and the `$theme_support_data` argument removed. * + * @param array $deprecated Deprecated. Not used. * @return WP_Theme_JSON Entity that holds theme data. */ public static function get_theme_data( $deprecated = array() ) { if ( ! empty( $deprecated ) ) { - _deprecated_argument( __METHOD__, '5.9' ); + _deprecated_argument( __METHOD__, '5.9.0' ); } if ( null === self::$theme ) { $theme_json_data = self::read_json_file( self::get_file_path_from_theme( 'theme.json' ) ); @@ -347,16 +348,16 @@ class WP_Theme_JSON_Resolver { * the user preference wins. * * @since 5.8.0 - * @since 5.9.0 Add user data and change the arguments. + * @since 5.9.0 Added user data, removed the `$settings` parameter, + * added the `$origin` parameter. * * @param string $origin Optional. To what level should we merge data. - * Valid values are 'theme' or 'custom'. - * Default is 'custom'. + * Valid values are 'theme' or 'custom'. Default 'custom'. * @return WP_Theme_JSON */ public static function get_merged_data( $origin = 'custom' ) { if ( is_array( $origin ) ) { - _deprecated_argument( __FUNCTION__, '5.9' ); + _deprecated_argument( __FUNCTION__, '5.9.0' ); } $result = new WP_Theme_JSON(); @@ -396,7 +397,7 @@ class WP_Theme_JSON_Resolver { * Whether the current theme has a theme.json file. * * @since 5.8.0 - * @since 5.9.0 Also check in the parent theme. + * @since 5.9.0 Added a check in the parent theme. * * @return bool */ @@ -417,7 +418,7 @@ class WP_Theme_JSON_Resolver { * If it isn't, returns an empty string, otherwise returns the whole file path. * * @since 5.8.0 - * @since 5.9.0 Adapt to work with child themes. + * @since 5.9.0 Adapted to work with child themes, added the `$template` argument. * * @param string $file_name Name of the file. * @param bool $template Optional. Use template theme directory. Default false. @@ -434,7 +435,8 @@ class WP_Theme_JSON_Resolver { * Cleans the cached data so it can be recalculated. * * @since 5.8.0 - * @since 5.9.0 Added new variables to reset. + * @since 5.9.0 Added the `$user`, `$user_custom_post_type_id`, + * and `$i18n_schema` variables to reset. */ public static function clean_cached_data() { self::$core = null; diff --git a/src/wp-includes/class-wp-theme-json.php b/src/wp-includes/class-wp-theme-json.php index 635f670cff..949727775c 100644 --- a/src/wp-includes/class-wp-theme-json.php +++ b/src/wp-includes/class-wp-theme-json.php @@ -82,7 +82,8 @@ class WP_Theme_JSON { * the value that takes a preset as an argument * (either value_key or value_func should be present) * - css_vars => template string to use in generating the CSS Custom Property. - * Example output: "--wp--preset--duotone--blue: " will generate as many CSS Custom Properties as presets defined + * Example output: "--wp--preset--duotone--blue: " will generate + * as many CSS Custom Properties as presets defined * substituting the $slug for the slug's value for each preset value. * - classes => array containing a structure with the classes to * generate for the presets, where for each array item @@ -99,7 +100,8 @@ class WP_Theme_JSON { * by means of the remove_insecure_properties method. * * @since 5.8.0 - * @since 5.9.0 Added new presets and simplified the metadata structure. + * @since 5.9.0 Added the `color/duotone` and `typography/fontFamily` presets, + * simplified the metadata structure. * @var array */ const PRESETS_METADATA = array( @@ -156,7 +158,10 @@ class WP_Theme_JSON { * path to the value in theme.json & block attributes. * * @since 5.8.0 - * @since 5.9.0 Added new properties and simplified the metadata structure. + * @since 5.9.0 Added the `border-*`, `font-family`, `font-style`, `font-weight`, + * `letter-spacing`, `margin-*`, `padding-*`, `--wp--style--block-gap`, + * `text-decoration`, `text-transform`, and `filter` properties, + * simplified the metadata structure. * @var array */ const PROPERTIES_METADATA = array( @@ -212,7 +217,8 @@ class WP_Theme_JSON { * The top-level keys a theme.json can have. * * @since 5.8.0 - * @since 5.9.0 Renamed from ALLOWED_TOP_LEVEL_KEYS and added new values. + * @since 5.9.0 Renamed from `ALLOWED_TOP_LEVEL_KEYS`, + * added the `customTemplates` and `templateParts` values. * @var string[] */ const VALID_TOP_LEVEL_KEYS = array( @@ -227,7 +233,9 @@ class WP_Theme_JSON { * The valid properties under the settings key. * * @since 5.8.0 - * @since 5.9.0 Renamed from ALLOWED_SETTINGS, gained new properties, and renamed others according to the new schema. + * @since 5.9.0 Renamed from `ALLOWED_SETTINGS`, added new properties + * for `border`, `color`, `spacing`, and `typography`, + * and renamed others according to the new schema. * @var array */ const VALID_SETTINGS = array( @@ -280,7 +288,8 @@ class WP_Theme_JSON { * The valid properties under the styles key. * * @since 5.8.0 - * @since 5.9.0 Renamed from ALLOWED_SETTINGS, gained new properties. + * @since 5.9.0 Renamed from `ALLOWED_SETTINGS`, added new properties + * for `border`, `filter`, `spacing`, and `typography`. * @var array */ const VALID_STYLES = array( @@ -335,7 +344,7 @@ class WP_Theme_JSON { * The latest version of the schema in use. * * @since 5.8.0 - * @since 5.9.0 Changed value. + * @since 5.9.0 Changed value from 1 to 2. * @var int */ const LATEST_SCHEMA = 2; @@ -435,10 +444,10 @@ class WP_Theme_JSON { * Sanitizes the input according to the schemas. * * @since 5.8.0 - * @since 5.9.0 Has new parameters. + * @since 5.9.0 Added the `$valid_block_names` and `$valid_element_name` parameters. * - * @param array $input Structure to sanitize. - * @param array $valid_block_names List of valid block names. + * @param array $input Structure to sanitize. + * @param array $valid_block_names List of valid block names. * @param array $valid_element_names List of valid element names. * @return array The sanitized output. */ @@ -518,7 +527,7 @@ class WP_Theme_JSON { * } * * @since 5.8.0 - * @since 5.9.0 Added duotone key with CSS selector. + * @since 5.9.0 Added `duotone` key with CSS selector. * * @return array Block metadata. */ @@ -632,19 +641,19 @@ class WP_Theme_JSON { * the theme.json structure this object represents. * * @since 5.8.0 - * @since 5.9.0 Changed the arguments passed to the function. + * @since 5.9.0 Removed the `$type` parameter`, added the `$types` and `$origins` parameters. * - * @param array $types Types of styles to load. Will load all by default. It accepts: - * 'variables': only the CSS Custom Properties for presets & custom ones. - * 'styles': only the styles section in theme.json. - * 'presets': only the classes for the presets. - * @param array $origins A list of origins to include. By default it includes self::VALID_ORIGINS. + * @param array $types Types of styles to load. Will load all by default. It accepts: + * - `variables`: only the CSS Custom Properties for presets & custom ones. + * - `styles`: only the styles section in theme.json. + * - `presets`: only the classes for the presets. + * @param array $origins A list of origins to include. By default it includes `self::VALID_ORIGINS`. * @return string Stylesheet. */ public function get_stylesheet( $types = array( 'variables', 'styles', 'presets' ), $origins = self::VALID_ORIGINS ) { if ( is_string( $types ) ) { // Dispatch error and map old arguments to new ones. - _deprecated_argument( __FUNCTION__, '5.9' ); + _deprecated_argument( __FUNCTION__, '5.9.0' ); if ( 'block_styles' === $types ) { $types = array( 'styles', 'presets' ); } elseif ( 'css_variables' === $types ) { @@ -736,7 +745,8 @@ class WP_Theme_JSON { * } * * @since 5.8.0 - * @since 5.9.0 Renamed to get_block_classes and no longer returns preset classes. + * @since 5.9.0 Renamed from `get_block_styles()` to `get_block_classes()` + * and no longer returns preset classes. * * @param array $style_nodes Nodes with styles. * @return string The new stylesheet. @@ -850,9 +860,9 @@ class WP_Theme_JSON { * } * * @since 5.8.0 - * @since 5.9.0 Added origins parameter. + * @since 5.9.0 Added the `$origins` parameter. * - * @param array $nodes Nodes with settings. + * @param array $nodes Nodes with settings. * @param array $origins List of origins to process. * @return string The new stylesheet. */ @@ -927,7 +937,7 @@ class WP_Theme_JSON { * for the preset classes. * * @since 5.8.0 - * @since 5.9.0 Added origins parameter. + * @since 5.9.0 Added the `$origins` parameter. * * @param array $settings Settings to process. * @param string $selector Selector wrapping the classes. @@ -979,7 +989,6 @@ class WP_Theme_JSON { * * @param string $scope Selector to scope to. * @param string $selector Original selector. - * * @return string Scoped selector. */ private static function scope_selector( $scope, $selector ) { @@ -1027,9 +1036,9 @@ class WP_Theme_JSON { * * @since 5.9.0 * - * @param array $settings Settings to process. + * @param array $settings Settings to process. * @param array $preset_metadata One of the PRESETS_METADATA values. - * @param array $origins List of origins to process. + * @param array $origins List of origins to process. * @return array Array of presets where each key is a slug and each value is the preset value. */ private static function get_settings_values_by_slug( $settings, $preset_metadata, $origins ) { @@ -1069,9 +1078,9 @@ class WP_Theme_JSON { * * @since 5.9.0 * - * @param array $settings Settings to process. + * @param array $settings Settings to process. * @param array $preset_metadata One of the PRESETS_METADATA values. - * @param array $origins List of origins to process. + * @param array $origins List of origins to process. * @return array Array of presets where the key and value are both the slug. */ private static function get_settings_slugs( $settings, $preset_metadata, $origins = self::VALID_ORIGINS ) { @@ -1098,8 +1107,8 @@ class WP_Theme_JSON { * @since 5.9.0 * * @param string $input String to replace. - * @param string $slug The slug value to use to generate the custom property. - * @return string The CSS Custom Property. Something along the lines of --wp--preset--color--black. + * @param string $slug The slug value to use to generate the custom property. + * @return string The CSS Custom Property. Something along the lines of `--wp--preset--color--black`. */ private static function replace_slug_in_string( $input, $slug ) { return strtr( $input, array( '$slug' => $slug ) ); @@ -1116,6 +1125,7 @@ class WP_Theme_JSON { * ) * * @since 5.8.0 + * @since 5.9.0 Added the `$origins` parameter. * * @param array $settings Settings to process. * @param array $origins List of origins to process. @@ -1234,10 +1244,10 @@ class WP_Theme_JSON { * ) * * @since 5.8.0 - * @since 5.9.0 Added theme setting and properties parameters. + * @since 5.9.0 Added the `$settings` and `$properties` parameters. * - * @param array $styles Styles to process. - * @param array $settings Theme settings. + * @param array $styles Styles to process. + * @param array $settings Theme settings. * @param array $properties Properties metadata. * @return array Returns the modified $declarations. */ @@ -1285,11 +1295,11 @@ class WP_Theme_JSON { * "--wp--preset--color--secondary". * * @since 5.8.0 - * @since 5.9.0 Consider $value that are arrays as well. + * @since 5.9.0 Added support for values of array type, which are returned as is. * * @param array $styles Styles subtree. * @param array $path Which property to process. - * @return string Style property value. + * @return string|array Style property value. */ private static function get_property_value( $styles, $path ) { $value = _wp_array_get( $styles, $path, '' ); @@ -1532,9 +1542,8 @@ class WP_Theme_JSON { * * @since 5.9.0 * - * @param array $data A theme.json like structure to inspect. - * @param array $node_path The path to inspect. It's 'settings' by default. - * + * @param array $data A theme.json like structure to inspect. + * @param array $node_path The path to inspect. Default is 'settings'. * @return array An associative array containing the slugs for the given path. */ private static function get_slugs_not_to_override( $data, $node_path = array( 'settings' ) ) { @@ -1568,11 +1577,10 @@ class WP_Theme_JSON { * * @since 5.9.0 * - * @param array $node The node with the presets to validate. - * @param array $path The path to the preset type to inspect. + * @param array $node The node with the presets to validate. + * @param array $path The path to the preset type to inspect. * @param array $slugs The slugs that should not be overriden. - * - * @return array The new node + * @return array The new node. */ private static function filter_slugs( $node, $path, $slugs ) { $slugs_for_preset = _wp_array_get( $slugs, $path, array() ); @@ -1739,9 +1747,9 @@ class WP_Theme_JSON { * * @since 5.9.0 * - * @param string $property_name Property name in a CSS declaration, i.e. the `color` in `color: red`. + * @param string $property_name Property name in a CSS declaration, i.e. the `color` in `color: red`. * @param string $property_value Value in a CSS declaration, i.e. the `red` in `color: red`. - * @return boolean + * @return bool */ private static function is_safe_css_declaration( $property_name, $property_value ) { $style_to_validate = $property_name . ': ' . $property_value;