PHPXRef 0.7.1 : WordPress Trunk (Updated Daily) : Detail view of class-wp-theme-json.php

Class: WP_Theme_JSON - X-Ref

Class that encapsulates the processing of structures that adhere to the theme.json spec.

This class is for internal core usage and is not supposed to be used by extenders (plugins and/or themes).
This is a low-level API that may need to do breaking changes. Please,
use get_global_settings, get_global_styles, and get_global_stylesheet instead.

schema_in_root_and_per_origin( $schema ) X-Ref

Return the input schema at the root and per origin.

param: array $schema The base schema.
return: array The schema at the root and per origin.

get_element_class_name( $element ) X-Ref

Returns a class name by an element name.

param: string $element The name of the element.
return: string The name of the class.

__construct( $theme_json = array( 'version' => self::LATEST_SCHEMA ) X-Ref

Constructor.

param: array $theme_json A structure that follows the theme.json schema.
param: string $origin Optional. What source of data this object represents.

unwrap_shared_block_style_variations( $theme_json, $valid_variations ) X-Ref

Unwraps shared block style variations.

It takes the shared variations (styles.variations.variationName) and
applies them to all the blocks that have the given variation registered
(styles.blocks.blockType.variations.variationName).

For example, given the `core/paragraph` and `core/group` blocks have
registered the `section-a` style variation, and given the following input:

{
"styles": {
"variations": {
"section-a": { "color": { "background": "backgroundColor" } }
}
}
}

It returns the following output:

{
"styles": {
"blocks": {
"core/paragraph": {
"variations": {
"section-a": { "color": { "background": "backgroundColor" } }
},
},
"core/group": {
"variations": {
"section-a": { "color": { "background": "backgroundColor" } }
}
}
}
}
}

param: array $theme_json A structure that follows the theme.json schema.
param: array $valid_variations Valid block style variations.
return: array Theme json data with shared variation definitions unwrapped under appropriate block types.

maybe_opt_in_into_settings( $theme_json ) X-Ref

Enables some opt-in settings if theme declared support.

param: array $theme_json A theme.json structure to modify.
return: array The modified theme.json structure.

do_opt_in_into_settings( &$context ) X-Ref

Enables some settings.

param: array $context The context to which the settings belong.

sanitize( $input, $valid_block_names, $valid_element_names, $valid_variations ) X-Ref

Sanitizes the input according to the schemas.

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.
param: array $valid_variations    List of valid variations per block.
return: array The sanitized output.

append_to_selector( $selector, $to_append ) X-Ref

Appends a sub-selector to an existing one.

Given the compounded $selector "h1, h2, h3"
and the $to_append selector ".some-class" the result will be
"h1.some-class, h2.some-class, h3.some-class".

param: string $selector Original selector.
param: string $to_append Selector to append.
return: string The new selector.

prepend_to_selector( $selector, $to_prepend ) X-Ref

Prepends a sub-selector to an existing one.

Given the compounded $selector "h1, h2, h3"
and the $to_prepend selector ".some-class " the result will be
".some-class h1, .some-class h2, .some-class h3".

param: string $selector Original selector.
param: string $to_prepend Selector to prepend.
return: string The new selector.

get_blocks_metadata() X-Ref

Returns the metadata for each block.

Example:

{
'core/paragraph': {
'selector': 'p',
'elements': {
'link' => 'link selector',
'etc' => 'element selector'
}
},
'core/heading': {
'selector': 'h1',
'elements': {}
},
'core/image': {
'selector': '.wp-block-image',
'duotone': 'img',
'elements': {}
}
}

return: array Block metadata.

remove_keys_not_in_schema( $tree, $schema ) X-Ref

Given a tree, removes the keys that are not present in the schema.

It is recursive and modifies the input in-place.

param: array $tree Input to process.
param: array $schema Schema to adhere to.
return: array The modified $tree.

get_settings() X-Ref

Returns the existing settings for each block.

Example:

{
'root': {
'color': {
'custom': true
}
},
'core/paragraph': {
'spacing': {
'customPadding': true
}
}
}

return: array Settings per block.

get_stylesheet( $types = array( 'variables', 'styles', 'presets' ) X-Ref

Returns the stylesheet that results of processing
the theme.json structure this object represents.

param: string[] $types Types of styles to load. Will load all by default. It accepts:
param: string[] $origins A list of origins to include. By default it includes VALID_ORIGINS.
param: array $options {
return: string The resulting stylesheet.

process_blocks_custom_css( $css, $selector ) X-Ref

Processes the CSS, to apply nesting.

param: string $css The CSS to process.
param: string $selector The selector to nest.
return: string The processed CSS.

get_custom_css() X-Ref

Returns the global styles custom CSS.

return: string The global styles custom CSS.

get_custom_templates() X-Ref

Returns the page templates of the active theme.

return: array

get_template_parts() X-Ref

Returns the template part data of active theme.

return: array

get_block_classes( $style_nodes ) X-Ref

Converts each style section into a list of rulesets
containing the block styles to be appended to the stylesheet.

See glossary at https://developer.mozilla.org/en-US/docs/Web/CSS/Syntax

For each section this creates a new ruleset such as:

block-selector {
style-property-one: value;
}

param: array $style_nodes Nodes with styles.
return: string The new stylesheet.

get_layout_styles( $block_metadata, $types = array() X-Ref

Gets the CSS layout rules for a particular block from theme.json layout definitions.

param: array $block_metadata Metadata about the block to get styles for.
param: array $types Optional. Types of styles to output. If empty, all styles will be output.
return: string Layout styles for the block.

get_preset_classes( $setting_nodes, $origins ) X-Ref

Creates new rulesets as classes for each preset value such as:

.has-value-color {
color: value;
}

.has-value-background-color {
background-color: value;
}

.has-value-font-size {
font-size: value;
}

.has-value-gradient-background {
background: value;
}

p.has-value-gradient-background {
background: value;
}

param: array $setting_nodes Nodes with settings.
param: string[] $origins List of origins to process presets from.
return: string The new stylesheet.

get_css_variables( $nodes, $origins ) X-Ref

Converts each styles section into a list of rulesets
to be appended to the stylesheet.
These rulesets contain all the css variables (custom variables and preset variables).

See glossary at https://developer.mozilla.org/en-US/docs/Web/CSS/Syntax

For each section this creates a new ruleset such as:

block-selector {
--wp--preset--category--slug: value;
--wp--custom--variable: value;
}

param: array $nodes Nodes with settings.
param: string[] $origins List of origins to process.
return: string The new stylesheet.

to_ruleset( $selector, $declarations ) X-Ref

Given a selector and a declaration list,
creates the corresponding ruleset.

param: string $selector CSS selector.
param: array $declarations List of declarations.
return: string The resulting CSS ruleset.

compute_preset_classes( $settings, $selector, $origins ) X-Ref

No description

scope_selector( $scope, $selector ) X-Ref

Function that scopes a selector with another one. This works a bit like
SCSS nesting except the `&` operator isn't supported.

<code>
$scope = '.a, .b .c';
$selector = '> .x, .y';
$merged = scope_selector( $scope, $selector );
// $merged is '.a > .x, .a .y, .b .c > .x, .b .c .y'
</code>

param: string $scope Selector to scope to.
param: string $selector Original selector.
return: string Scoped selector.

scope_style_node_selectors( $scope, $node ) X-Ref

Scopes the selectors for a given style node.

This includes the primary selector, i.e. `$node['selector']`, as well as any custom
selectors for features and subfeatures, e.g. `$node['selectors']['border']` etc.

param: string $scope Selector to scope to.
param: array $node Style node with selectors to scope.
return: array Node with updated selectors.

get_settings_values_by_slug( $settings, $preset_metadata, $origins ) X-Ref

Gets preset values keyed by slugs based on settings and metadata.

<code>
$settings = array(
'typography' => array(
'fontFamilies' => array(
array(
'slug'       => 'sansSerif',
'fontFamily' => '"Helvetica Neue", sans-serif',
),
array(
'slug'   => 'serif',
'colors' => 'Georgia, serif',
)
),
),
);
$meta = array(
'path'      => array( 'typography', 'fontFamilies' ),
'value_key' => 'fontFamily',
);
$values_by_slug = get_settings_values_by_slug();
// $values_by_slug === array(
//   'sans-serif' => '"Helvetica Neue", sans-serif',
//   'serif'      => 'Georgia, serif',
// );
</code>

param: array    $settings        Settings to process.
param: array    $preset_metadata One of the PRESETS_METADATA values.
param: string[] $origins         List of origins to process.
return: array Array of presets where each key is a slug and each value is the preset value.

get_settings_slugs( $settings, $preset_metadata, $origins = null ) X-Ref

Similar to get_settings_values_by_slug, but doesn't compute the value.

param: array    $settings        Settings to process.
param: array    $preset_metadata One of the PRESETS_METADATA values.
param: string[] $origins         List of origins to process.
return: array Array of presets where the key and value are both the slug.

replace_slug_in_string( $input, $slug ) X-Ref

Transforms a slug into a CSS Custom Property.

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`.

compute_preset_vars( $settings, $origins ) X-Ref

Given the block settings, extracts the CSS Custom Properties
for the presets and adds them to the $declarations array
following the format:

array(
'name'  => 'property_name',
'value' => 'property_value,
)

param: array    $settings Settings to process.
param: string[] $origins  List of origins to process.
return: array The modified $declarations.

compute_theme_vars( $settings ) X-Ref

Given an array of settings, extracts the CSS Custom Properties
for the custom values and adds them to the $declarations
array following the format:

array(
'name' => 'property_name',
'value' => 'property_value,
)

param: array $settings Settings to process.
return: array The modified $declarations.

flatten_tree( $tree, $prefix = '', $token = '--' ) X-Ref

Given a tree, it creates a flattened one
by merging the keys and binding the leaf values
to the new keys.

It also transforms camelCase names into kebab-case
and substitutes '/' by '-'.

This is thought to be useful to generate
CSS Custom Properties from a tree,
although there's nothing in the implementation
of this function that requires that format.

For example, assuming the given prefix is '--wp'
and the token is '--', for this input tree:

{
'some/property': 'value',
'nestedProperty': {
'sub-property': 'value'
}
}

it'll return this output:

{
'--wp--some-property': 'value',
'--wp--nested-property--sub-property': 'value'
}

param: array $tree Input tree to process.
param: string $prefix Optional. Prefix to prepend to each variable. Default empty string.
param: string $token Optional. Token to use between levels. Default '--'.
return: array The flattened tree.

compute_style_properties( $styles, $settings = array() X-Ref

Given a styles array, it extracts the style properties
and adds them to the $declarations array following the format:

array(
'name'  => 'property_name',
'value' => 'property_value',
)

param: array   $styles Styles to process.
param: array   $settings Theme settings.
param: array   $properties Properties metadata.
param: array   $theme_json Theme JSON array.
param: string  $selector The style block selector.
param: boolean $use_root_padding Whether to add custom properties at root level.
return: array Returns the modified $declarations.

get_property_value( $styles, $path, $theme_json = null ) X-Ref

Returns the style property for the given path.

It also converts references to a path to the value
stored at that location, e.g.
{ "ref": "style.color.background" } => "#fff".

param: array $styles Styles subtree.
param: array $path Which property to process.
param: array $theme_json Theme JSON array.
return: string|array Style property value.

get_setting_nodes( $theme_json, $selectors = array() X-Ref

Builds metadata for the setting nodes, which returns in the form of:

[
[
'path'     => ['path', 'to', 'some', 'node' ],
'selector' => 'CSS selector for some node'
],
[
'path'     => [ 'path', 'to', 'other', 'node' ],
'selector' => 'CSS selector for other node'
],
]

param: array $theme_json The tree to extract setting nodes from.
param: array $selectors  List of selectors per block.
return: array An array of setting nodes metadata.

get_style_nodes( $theme_json, $selectors = array() X-Ref

Builds metadata for the style nodes, which returns in the form of:

[
[
'path'     => [ 'path', 'to', 'some', 'node' ],
'selector' => 'CSS selector for some node',
'duotone'  => 'CSS selector for duotone for some node'
],
[
'path'     => ['path', 'to', 'other', 'node' ],
'selector' => 'CSS selector for other node',
'duotone'  => null
],
]

param: array $theme_json The tree to extract style nodes from.
param: array $selectors  List of selectors per block.
param: array $options {
return: array An array of style nodes metadata.

get_styles_block_nodes() X-Ref

A public helper to get the block nodes from a theme.json file.

return: array The block nodes in theme.json.

update_separator_declarations( $declarations ) X-Ref

Returns a filtered declarations array if there is a separator block with only a background
style defined in theme.json by adding a color attribute to reflect the changes in the front.

param: array $declarations List of declarations.
return: array $declarations List of declarations filtered.

get_block_nodes( $theme_json, $selectors = array() X-Ref

An internal method to get the block nodes from a theme.json file.

param: array $theme_json The theme.json converted to an array.
param: array $selectors Optional list of selectors per block.
param: array $options {
return: array The block nodes in theme.json.

get_styles_for_block( $block_metadata ) X-Ref

Gets the CSS rules for a particular block from theme.json.

param: array $block_metadata Metadata about the block to get styles for.
return: string Styles for the block.

get_root_layout_rules( $selector, $block_metadata ) X-Ref

No description

get_metadata_boolean( $data, $path, $default_value = false ) X-Ref

For metadata values that can either be booleans or paths to booleans, gets the value.

$data = array(
'color' => array(
'defaultPalette' => true
)
);

static::get_metadata_boolean( $data, false );
// => false

static::get_metadata_boolean( $data, array( 'color', 'defaultPalette' ) );
// => true

param: array      $data          The data to inspect.
param: bool|array $path          Boolean or path to a boolean.
param: bool       $default_value Default value if the referenced path is missing.
return: bool Value of boolean metadata.

merge( $incoming ) X-Ref

Merges new incoming data.

param: WP_Theme_JSON $incoming Data to merge.

get_svg_filters( $origins ) X-Ref

Converts all filter (duotone) presets into SVGs.

param: array $origins List of origins to process.
return: string SVG filters.

should_override_preset( $theme_json, $path, $override ) X-Ref

Determines whether a presets should be overridden or not.

param: array      $theme_json The theme.json like structure to inspect.
param: array      $path       Path to inspect.
param: bool|array $override   Data to compute whether to override the preset.
return: bool

get_default_slugs( $data, $node_path ) X-Ref

Returns the default slugs for all the presets in an associative array
whose keys are the preset paths and the leaves is the list of slugs.

For example:

array(
'color' => array(
'palette' => array( 'slug-1', 'slug-2' ),
'gradients' => array( 'slug-3', 'slug-4' ),
),
)

param: array $data A theme.json like structure.
param: array $node_path The path to inspect. It's 'settings' by default.
return: array

get_name_from_defaults( $slug, $base_path ) X-Ref

Gets a `default`'s preset name by a provided slug.

param: string $slug The slug we want to find a match from default presets.
param: array $base_path The path to inspect. It's 'settings' by default.
return: string|null

filter_slugs( $node, $slugs ) X-Ref

Removes the preset values whose slug is equal to any of given slugs.

param: array $node The node with the presets to validate.
param: array $slugs The slugs that should not be overridden.
return: array The new node.

remove_insecure_properties( $theme_json, $origin = 'theme' ) X-Ref

Removes insecure data from theme.json.

param: array $theme_json Structure to sanitize.
param: string $origin Optional. What source of data this object represents.
return: array Sanitized structure.

remove_insecure_settings( $input ) X-Ref

Processes a setting node and returns the same node
without the insecure settings.

param: array $input Node to process.
return: array

remove_insecure_styles( $input ) X-Ref

Processes a style node and returns the same node
without the insecure styles.

param: array $input Node to process.
return: array

is_safe_css_declaration( $property_name, $property_value ) X-Ref

Checks that a declaration provided by the user is safe.

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: bool

remove_indirect_properties( $input, &$output ) X-Ref

Removes indirect properties from the given input node and
sets in the given output node.

param: array $input Node to process.
param: array $output The processed node. Passed by reference.

get_raw_data() X-Ref

Returns the raw data.

return: array Raw data.

get_from_editor_settings( $settings ) X-Ref

Transforms the given editor settings according the
add_theme_support format to the theme.json format.

param: array $settings Existing editor settings.
return: array Config that adheres to the theme.json schema.

get_patterns() X-Ref

Returns the current theme's wanted patterns(slugs) to be
registered from Pattern Directory.

return: string[]

get_data() X-Ref

Returns a valid theme.json as provided by a theme.

Unlike get_raw_data() this returns the presets flattened, as provided by a theme.
This also uses appearanceTools instead of their opt-ins if all of them are true.

return: array

set_spacing_sizes() X-Ref

Sets the spacingSizes array based on the spacingScale values from theme.json.

return: null|void

merge_spacing_sizes( $base, $incoming ) X-Ref

Merges two sets of spacing size presets.

param: array $base The base set of spacing sizes.
param: array $incoming The set of spacing sizes to merge with the base. Duplicate slugs will override the base values.
return: array The merged set of spacing sizes.

compute_spacing_sizes( $spacing_scale ) X-Ref

Generates a set of spacing sizes by starting with a medium size and
applying an operator with an increment value to generate the rest of the
sizes outward from the medium size. The medium slug is '50' with the rest
of the slugs being 10 apart. The generated names use t-shirt sizing.

Example:

$spacing_scale = array(
'steps'      => 4,
'mediumStep' => 16,
'unit'       => 'px',
'operator'   => '+',
'increment'  => 2,
);
$spacing_sizes = static::compute_spacing_sizes( $spacing_scale );
// -> array(
//        array( 'name' => 'Small',   'slug' => '40', 'size' => '14px' ),
//        array( 'name' => 'Medium',  'slug' => '50', 'size' => '16px' ),
//        array( 'name' => 'Large',   'slug' => '60', 'size' => '18px' ),
//        array( 'name' => 'X-Large', 'slug' => '70', 'size' => '20px' ),
//    )

param: array $spacing_scale {
return: array The spacing sizes presets or an empty array if some spacing scale values are missing or invalid.

convert_custom_properties( $value ) X-Ref

This is used to convert the internal representation of variables to the CSS representation.
For example, `var:preset|color|vivid-green-cyan` becomes `var(--wp--preset--color--vivid-green-cyan)`.

param: string $value The variable such as var:preset|color|vivid-green-cyan to convert.
return: string The converted variable.

resolve_custom_css_format( $tree ) X-Ref

Given a tree, converts the internal representation of variables to the CSS representation.
It is recursive and modifies the input in-place.

param: array $tree Input to process.
return: array The modified $tree.

get_block_selectors( $block_type, $root_selector ) X-Ref

Returns the selectors metadata for a block.

param: object $block_type The block type.
param: string $root_selector The block's root selector.
return: array The custom selectors set by the block.

get_block_element_selectors( $root_selector ) X-Ref

Generates all the element selectors for a block.

param: string $root_selector The block's root CSS selector.
return: array The block's element selectors.

get_feature_declarations_for_node( $metadata, &$node ) X-Ref

Generates style declarations for a node's features e.g., color, border,
typography etc. that have custom selectors in their related block's
metadata.

param: object $metadata The related block metadata containing selectors.
param: object $node A merged theme.json node for block or variation.
return: array The style declarations for the node's features with custom

convert_variables_to_value( $styles, $values ) X-Ref

Replaces CSS variables with their values in place.

param: array $styles CSS declarations to convert.
param: array $values key => value pairs to use for replacement.
return: array

resolve_variables( $theme_json ) X-Ref

Resolves the values of CSS variables in the given styles.

param: WP_Theme_JSON $theme_json The theme json resolver.
return: WP_Theme_JSON The $theme_json with resolved variables.

get_block_style_variation_selector( $variation_name, $block_selector ) X-Ref

No description

get_valid_block_style_variations( $blocks_metadata = array() X-Ref

No description

File Size:	4565 lines (162 kb)
Included or required:	0 times
Referenced:	0 times
Includes or requires:	0 files

PHP Cross Reference of WordPress Trunk (Updated Daily)

/wp-includes/ -> class-wp-theme-json.php (summary)

Defines 1 class