Skip to content

Commit

Permalink
Formatting PHP doc comments and params that describe associative arrays
Browse files Browse the repository at this point in the history 
Updating test function names and annotations.
  • Loading branch information
@ramonjd
ramonjd committed Sep 8, 2022
1 parent 30b3afe commit 0166739
Show file tree
Hide file tree
Showing 8 changed files with 323 additions and 178 deletions.
82 changes: 48 additions & 34 deletions src/wp-includes/style-engine.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,19 +25,22 @@
* @access public
* @since 6.1.0
*
* @param array $block_styles The style object.
* @param array<string|boolean> $options array(
* 'context' => (string|null) An identifier describing the origin of the style object, e.g., 'block-supports' or 'global-styles'. Default is 'block-supports'.
* When set, the style engine will attempt to store the CSS rules, where a selector is also passed.
* 'convert_vars_to_classnames' => (boolean) Whether to skip converting CSS var:? values to var( --wp--preset--* ) values. Default is `false`.
* 'selector' => (string) When a selector is passed, `generate()` will return a full CSS rule `$selector { ...rules }`, otherwise a concatenated string of properties and values.
* );.
*
* @return array<string|array> array(
* 'css' => (string) A CSS ruleset or declarations block formatted to be placed in an HTML `style` attribute or tag.
* 'declarations' => (array) An array of property/value pairs representing parsed CSS declarations.
* 'classnames' => (string) Classnames separated by a space.
* );
* @param array $block_styles The style object.
* @param array $options {
* Optional. An array of options. Default empty array.
*
* @type string|null $context An identifier describing the origin of the style object, e.g., 'block-supports' or 'global-styles'. Default is `null`.
* When set, the style engine will attempt to store the CSS rules, where a selector is also passed.
* @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`, to var( --wp--preset--* ) values. Default `false`.
* @type string $selector Optional. When a selector is passed, the value of `$css` in the return value will comprise a full CSS rule `$selector { ...$css_declarations }`,
* otherwise, the value will be a concatenated string of CSS declarations.
* }
*
* @return array {
* @type string $css A CSS ruleset or declarations block formatted to be placed in an HTML `style` attribute or tag.
* @type array<string, string> $declarations An array of property/value pairs representing parsed CSS declarations.
* @type string $classnames Classnames separated by a space.
* }
*/
function wp_style_engine_get_styles( $block_styles, $options = array() ) {
if ( ! class_exists( 'WP_Style_Engine' ) ) {
Expand Down Expand Up @@ -75,23 +78,32 @@ function wp_style_engine_get_styles( $block_styles, $options = array() ) {

/**
* Returns compiled CSS from a collection of selectors and declarations.
* This won't add to any store, but is useful for returning a compiled style sheet from any CSS selector + declarations combos.
* Useful for returning a compiled stylesheet from any collection of CSS selector + declarations.
*
* Example usage:
* $css_rules = array( array( 'selector' => '.elephant-are-cool', 'declarations' => array( 'color' => 'gray', 'width' => '3em' ) ) );
* $css = wp_style_engine_get_stylesheet_from_css_rules( $css_rules );
* // Returns `.elephant-are-cool{color:gray;width:3em}`.
*
* @access public
* @since 6.1.0
*
* @param array<array> $css_rules array(
* array(
* 'selector' => (string) A CSS selector.
* declarations' => (boolean) An array of CSS definitions, e.g., array( "$property" => "$value" ).
* )
* );.
* @param array<string> $options array(
* 'context' => (string|null) An identifier describing the origin of the style object, e.g., 'block-supports' or 'global-styles'. Default is 'block-supports'.
* When set, the style engine will attempt to store the CSS rules.
* 'optimize' => (boolean) Whether to optimize the CSS output, e.g., combine rules.
* 'prettify' => (boolean) Whether to add new lines to output.
* );.
* @param array $css_rules {
* Required. A collection of CSS rules.
*
* @type array ...$0 {
* @type string $selector A CSS selector.
* @type array<string, string> $declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
* }
* }
* @param array $options {
* Optional. An array of options. Default empty array.
*
* @type string|null $context An identifier describing the origin of the style object, e.g., 'block-supports' or 'global-styles'. Default is 'block-supports'.
* When set, the style engine will attempt to store the CSS rules.
* @type boolean $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`.
* @type boolean $prettify Whether to add new lines and indents to output. Default is the test of whether the global constant `SCRIPT_DEBUG` is defined.
* }
*
* @return string A compiled CSS string.
*/
Expand Down Expand Up @@ -133,18 +145,20 @@ function wp_style_engine_get_stylesheet_from_css_rules( $css_rules, $options = a
* @access public
* @since 6.1.0
*
* @param string $store_name A valid store name.
* @param array $options array(
* 'optimize' => (boolean) Whether to optimize the CSS output, e.g., combine rules.
* 'prettify' => (boolean) Whether to add new lines to output.
* );.
* @param string $context A valid context name, corresponding to an existing store key.
* @param array $options {
* Optional. An array of options. Default empty array.
*
* @type boolean $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`.
* @type boolean $prettify Whether to add new lines and indents to output. Default is the test of whether the global constant `SCRIPT_DEBUG` is defined.
* }
*
* @return string A compiled CSS string.
*/
function wp_style_engine_get_stylesheet_from_context( $store_name, $options = array() ) {
if ( ! class_exists( 'WP_Style_Engine' ) || empty( $store_name ) ) {
function wp_style_engine_get_stylesheet_from_context( $context, $options = array() ) {
if ( ! class_exists( 'WP_Style_Engine' ) || empty( $context ) ) {
return '';
}

return WP_Style_Engine::compile_stylesheet_from_css_rules( WP_Style_Engine::get_store( $store_name )->get_all_rules(), $options );
return WP_Style_Engine::compile_stylesheet_from_css_rules( WP_Style_Engine::get_store( $context )->get_all_rules(), $options );
}
11 changes: 7 additions & 4 deletions src/wp-includes/style-engine/class-wp-style-engine-processor.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,7 @@ public function add_rules( $css_rules ) {
if ( ! is_array( $css_rules ) ) {
$css_rules = array( $css_rules );
}

foreach ( $css_rules as $rule ) {
$selector = $rule->get_selector();
if ( isset( $this->css_rules[ $selector ] ) ) {
Expand All @@ -80,10 +81,12 @@ public function add_rules( $css_rules ) {
*
* @since 6.1.0
*
* @param array $options array(
* 'optimize' => (boolean) Whether to optimize the CSS output, e.g., combine rules.
* 'prettify' => (boolean) Whether to add new lines to output.
* );.
* @param array $options {
* Optional. An array of options. Default empty array.
*
* @type boolean $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`.
* @type boolean $prettify Whether to add new lines and indents to output. Default is the test of whether the global constant `SCRIPT_DEBUG` is defined.
* }
*
* @return string The computed CSS.
*/
Expand Down
83 changes: 46 additions & 37 deletions src/wp-includes/style-engine/class-wp-style-engine.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -275,9 +275,9 @@ protected static function is_valid_style_value( $style_value ) {
*
* @since 6.1.0
*
* @param string $store_name A valid store key.
* @param string $css_selector When a selector is passed, the function will return a full CSS rule `$selector { ...rules }`, otherwise a concatenated string of properties and values.
* @param array $css_declarations An array of parsed CSS property => CSS value pairs.
* @param string $store_name A valid store key.
* @param string $css_selector When a selector is passed, the function will return a full CSS rule `$selector { ...rules }`, otherwise a concatenated string of properties and values.
* @param array<string, string> $css_declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
*
* @return void.
*/
Expand Down Expand Up @@ -308,15 +308,18 @@ public static function get_store( $store_name ) {
* @since 6.1.0
*
* @param array $block_styles The style object.
* @param array $options array(
* 'selector' => (string) When a selector is passed, `generate()` will return a full CSS rule `$selector { ...rules }`, otherwise a concatenated string of properties and values.
* 'convert_vars_to_classnames' => (boolean) Whether to skip converting CSS var:? values to var( --wp--preset--* ) values. Default is `false`.
* );.
*
* @return array array(
* 'declarations' => (array) An array of parsed CSS property => CSS value pairs.
* 'classnames' => (array) A flat array of classnames.
* );
* @param array $options {
* Optional. An array of options. Default empty array.
*
* @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`, to var( --wp--preset--* ) values. Default `false`.
* @type string $selector Optional. When a selector is passed, the value of `$css` in the return value will comprise a full CSS rule `$selector { ...$css_declarations }`,
* otherwise, the value will be a concatenated string of CSS declarations.
* }
*
* @return array {
* @type string $classnames Classnames separated by a space.
* @type array<string, string> $declarations An array of property/value pairs representing parsed CSS declarations.
* }
*/
public static function parse_block_styles( $block_styles, $options ) {
$parsed_styles = array(
Expand Down Expand Up @@ -348,14 +351,14 @@ public static function parse_block_styles( $block_styles, $options ) {
}

/**
* Returns classnames, and generates classname(s) from a CSS preset property pattern, e.g., 'var:preset|color|heavenly-blue'.
* Returns classnames, and generates classname(s) from a CSS preset property pattern, e.g., '`var:preset|<PRESET_TYPE>|<PRESET_SLUG>`'.
*
* @since 6.1.0
*
* @param array $style_value A single raw style value or css preset property from the generate() $block_styles array.
* @param array<string> $style_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA.
* @param array $style_value A single raw style value or css preset property from the $block_styles array.
* @param array $style_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA.
*
* @return array An array of CSS classnames.
* @return array<string> An array of CSS classnames.
*/
protected static function get_classnames( $style_value, $style_definition ) {
if ( empty( $style_value ) ) {
Expand Down Expand Up @@ -389,15 +392,17 @@ protected static function get_classnames( $style_value, $style_definition ) {
*
* @since 6.1.0
*
* @param array $style_value A single raw style value from the generate() $block_styles array.
* @param array<string> $style_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA.
* @param array $options array(
* 'convert_vars_to_classnames' => (boolean) Whether to skip converting CSS var:? values to var( --wp--preset--* ) values. Default is `false`.
* );.
* @param array $style_value A single raw style value from $block_styles array.
* @param array $style_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA.
* @param array $options {
* Optional. An array of options. Default empty array.
*
* @return array An array of CSS definitions, e.g., array( "$property" => "$value" ).
* @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`, to var( --wp--preset--* ) values. Default `false`.
* }
*
* @return array<string, string> An array of CSS definitions, e.g., array( "$property" => "$value" ).
*/
protected static function get_css_declarations( $style_value, $style_definition, $options ) {
protected static function get_css_declarations( $style_value, $style_definition, $options = array() ) {
if ( isset( $style_definition['value_func'] ) && is_callable( $style_definition['value_func'] ) ) {
return call_user_func( $style_definition['value_func'], $style_value, $style_definition, $options );
}
Expand All @@ -406,7 +411,7 @@ protected static function get_css_declarations( $style_value, $style_definition,
$style_property_keys = $style_definition['property_keys'];
$should_skip_css_vars = isset( $options['convert_vars_to_classnames'] ) && true === $options['convert_vars_to_classnames'];

// Build CSS var values from var:? values, e.g, `var(--wp--css--rule-slug )`
// Build CSS var values from `var:preset|<PRESET_TYPE>|<PRESET_SLUG>` values, e.g, `var(--wp--css--rule-slug )`.
// Check if the value is a CSS preset and there's a corresponding css_var pattern in the style definition.
if ( is_string( $style_value ) && str_contains( $style_value, 'var:' ) ) {
if ( ! $should_skip_css_vars && ! empty( $style_definition['css_vars'] ) ) {
Expand Down Expand Up @@ -455,15 +460,17 @@ protected static function get_css_declarations( $style_value, $style_definition,
*
* @since 6.1.0
*
* @param array $style_value A single raw Gutenberg style attributes value for a CSS property.
* @param array $individual_property_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA.
* @param array $options array(
* 'convert_vars_to_classnames' => (boolean) Whether to skip converting CSS var:? values to var( --wp--preset--* ) values. Default is `false`.
* );.
* @param array $style_value A single raw style value from $block_styles array.
* @param array $individual_property_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA representing an individual property of a CSS property, e.g., 'top' in 'border-top'.
* @param array $options {
* Optional. An array of options. Default empty array.
*
* @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`, to var( --wp--preset--* ) values. Default `false`.
* }
*
* @return array An array of CSS definitions, e.g., array( "$property" => "$value" ).
* @return array<string, string> An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
*/
protected static function get_individual_property_css_declarations( $style_value, $individual_property_definition, $options ) {
protected static function get_individual_property_css_declarations( $style_value, $individual_property_definition, $options = array() ) {
if ( ! is_array( $style_value ) || empty( $style_value ) || empty( $individual_property_definition['path'] ) ) {
return array();
}
Expand Down Expand Up @@ -502,8 +509,8 @@ protected static function get_individual_property_css_declarations( $style_value
*
* @since 6.1.0
*
* @param array $css_declarations An array of parsed CSS property => CSS value pairs.
* @param string $css_selector When a selector is passed, the function will return a full CSS rule `$selector { ...rules }`, otherwise a concatenated string of properties and values.
* @param array<string, string> $css_declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
* @param string $css_selector When a selector is passed, the function will return a full CSS rule `$selector { ...rules }`, otherwise a concatenated string of properties and values.
*
* @return string A compiled CSS string.
*/
Expand All @@ -528,10 +535,12 @@ public static function compile_css( $css_declarations, $css_selector ) {
* @since 6.1.0
*
* @param WP_Style_Engine_CSS_Rule[] $css_rules An array of WP_Style_Engine_CSS_Rule objects from a store or otherwise.
* @param array $options array(
* 'optimize' => (boolean) Whether to optimize the CSS output, e.g., combine rules.
* 'prettify' => (boolean) Whether to add new lines to output.
* );.
* @param array $options {
* Optional. An array of options. Default empty array.
*
* @type boolean $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`.
* @type boolean $prettify Whether to add new lines and indents to output. Default is the test of whether the global constant `SCRIPT_DEBUG` is defined.
* }
*
* @return string A compiled stylesheet from stored CSS rules.
*/
Expand Down
Loading

0 comments on commit 0166739

Please sign in to comment.