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.

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

get_element_class_name( $element ) X-Ref

Returns a class name by an element name.

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

__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" } }
}
}
}
}
}

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

maybe_opt_in_into_settings( $theme_json ) X-Ref

Enables some opt-in settings if theme declared support.

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

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.

return: array The sanitized output.
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.

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

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

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

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

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.

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

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.

return: string The resulting stylesheet.
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 {

process_blocks_custom_css( $css, $selector ) X-Ref

Processes the CSS, to apply nesting.

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

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;
}

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

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

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

return: string Layout styles for the block.
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.

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;
}

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

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;
}

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

to_ruleset( $selector, $declarations ) X-Ref

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

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

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>

return: string Scoped selector.
param: string $scope Selector to scope to.
param: string $selector Original 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.

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

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>

return: array Array of presets where each key is a slug and each value is the preset 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.

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

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

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

replace_slug_in_string( $input, $slug ) X-Ref

Transforms a slug into a CSS Custom Property.

return: string The CSS Custom Property. Something along the lines of `--wp--preset--color--black`.
param: string $input String to replace.
param: string $slug The slug value to use to generate the custom property.

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,
)

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

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,
)

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

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'
}

return: array The flattened tree.
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 '--'.

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',
)

return: array Returns the modified $declarations.
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.

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

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

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'
],
]

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

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
],
]

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

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.

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

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

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

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

get_styles_for_block( $block_metadata ) X-Ref

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

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

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

return: bool Value of boolean metadata.
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.

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.

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

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

Determines whether a presets should be overridden or not.

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

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' ),
),
)

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

get_name_from_defaults( $slug, $base_path ) X-Ref

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

return: string|null
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.

filter_slugs( $node, $slugs ) X-Ref

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

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

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

Removes insecure data from theme.json.

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

remove_insecure_settings( $input ) X-Ref

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

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

remove_insecure_styles( $input ) X-Ref

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

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

is_safe_css_declaration( $property_name, $property_value ) X-Ref

Checks that a declaration provided by the user is safe.

return: bool
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`.

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.

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

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.

return: array The merged set of spacing sizes.
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.

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' ),
//    )

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

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

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

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.

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

get_block_selectors( $block_type, $root_selector ) X-Ref

Returns the selectors metadata for a block.

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

get_block_element_selectors( $root_selector ) X-Ref

Generates all the element selectors for a block.

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

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.

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

convert_variables_to_value( $styles, $values ) X-Ref

Replaces CSS variables with their values in place.

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

resolve_variables( $theme_json ) X-Ref

Resolves the values of CSS variables in the given styles.

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

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