Style engine: rename public method (#42140)

* Renames wp_style_engine_generate to wp_style_engine_generate_block_styles to better describe the first (and required) argument: a single block style object. Renaming references from styles to declarations for clarity. Adding PHP doc comments to tests. * Renaming the `generate` public method to `generate_block_styles` * Rename method to refer to `block_supports` to differentiate from block styles, which is an existing paradigm that pertains to "style variations".
WordPress · Jul 6, 2022 · 0933055 · 0933055
1 parent 78d3661
commit 0933055
Show file tree

Hide file tree

Showing 8 changed files with 53 additions and 51 deletions.
diff --git a/lib/block-supports/border.php b/lib/block-supports/border.php
@@ -119,7 +119,7 @@ function gutenberg_apply_border_support( $block_type, $block_attributes ) {
 
 	// Collect classes and styles.
 	$attributes = array();
-	$styles     = gutenberg_style_engine_generate( array( 'border' => $border_block_styles ) );
+	$styles     = gutenberg_style_engine_get_block_supports_styles( array( 'border' => $border_block_styles ) );
 
 	if ( ! empty( $styles['classnames'] ) ) {
 		$attributes['class'] = $styles['classnames'];

diff --git a/lib/block-supports/colors.php b/lib/block-supports/colors.php
@@ -102,7 +102,7 @@ function gutenberg_apply_colors_support( $block_type, $block_attributes ) {
 	}
 
 	$attributes = array();
-	$styles     = gutenberg_style_engine_generate( array( 'color' => $color_block_styles ), array( 'convert_vars_to_classnames' => true ) );
+	$styles     = gutenberg_style_engine_get_block_supports_styles( array( 'color' => $color_block_styles ), array( 'convert_vars_to_classnames' => true ) );
 
 	if ( ! empty( $styles['classnames'] ) ) {
 		$attributes['class'] = $styles['classnames'];

diff --git a/lib/block-supports/elements.php b/lib/block-supports/elements.php
@@ -105,7 +105,7 @@ function gutenberg_render_elements_support_styles( $pre_render, $block ) {
 	$link_block_styles = isset( $element_block_styles['link'] ) ? $element_block_styles['link'] : null;
 
 	if ( $link_block_styles ) {
-		$styles = gutenberg_style_engine_generate(
+		$styles = gutenberg_style_engine_get_block_supports_styles(
 			$link_block_styles,
 			array(
 				'selector' => ".$class_name a",

diff --git a/lib/block-supports/spacing.php b/lib/block-supports/spacing.php
@@ -57,7 +57,7 @@ function gutenberg_apply_spacing_support( $block_type, $block_attributes ) {
 	$spacing_block_styles            = array();
 	$spacing_block_styles['padding'] = $has_padding_support && ! $skip_padding ? _wp_array_get( $block_styles, array( 'spacing', 'padding' ), null ) : null;
 	$spacing_block_styles['margin']  = $has_margin_support && ! $skip_margin ? _wp_array_get( $block_styles, array( 'spacing', 'margin' ), null ) : null;
-	$styles                          = gutenberg_style_engine_generate( array( 'spacing' => $spacing_block_styles ) );
+	$styles                          = gutenberg_style_engine_get_block_supports_styles( array( 'spacing' => $spacing_block_styles ) );
 
 	if ( ! empty( $styles['css'] ) ) {
 		$attributes['style'] = $styles['css'];

diff --git a/lib/block-supports/typography.php b/lib/block-supports/typography.php
@@ -141,7 +141,7 @@ function gutenberg_apply_typography_support( $block_type, $block_attributes ) {
 	}
 
 	$attributes = array();
-	$styles     = gutenberg_style_engine_generate(
+	$styles     = gutenberg_style_engine_get_block_supports_styles(
 		array( 'typography' => $typography_block_styles ),
 		array( 'convert_vars_to_classnames' => true )
 	);

diff --git a/packages/style-engine/class-wp-style-engine-css-declarations.php b/packages/style-engine/class-wp-style-engine-css-declarations.php
@@ -12,32 +12,32 @@
 }
 
 /**
- * Holds, sanitizes, processes and prints CSS styles rules declarations for the style engine.
+ * Holds, sanitizes, processes and prints CSS declarations for the style engine.
  *
  * @access private
  */
 class WP_Style_Engine_CSS_Declarations {
 
 	/**
-	 * An array of styles (property => value pairs).
+	 * An array of CSS declarations (property => value pairs).
 	 *
 	 * @var array
 	 */
-	protected $styles = array();
+	protected $declarations = array();
 
 	/**
-	 * Contructor for this object.
+	 * Constructor for this object.
 	 *
-	 * If a `$styles` array is passed, it will be used to populate
-	 * the initial $styles prop of the object by calling add_declarations().
+	 * If a `$declarations` array is passed, it will be used to populate
+	 * the initial $declarations prop of the object by calling add_declarations().
 	 *
-	 * @param array $styles An array of styles (property => value pairs).
+	 * @param array $declarations An array of declarations (property => value pairs).
 	 */
-	public function __construct( $styles = array() ) {
-		if ( empty( $styles ) ) {
+	public function __construct( $declarations = array() ) {
+		if ( empty( $declarations ) ) {
 			return;
 		}
-		$this->add_declarations( $styles );
+		$this->add_declarations( $declarations );
 	}
 
 	/**
@@ -63,8 +63,8 @@ public function add_declaration( $property, $value ) {
 			return;
 		}
 
-		// Add the style.
-		$this->styles[ $property ] = $value;
+		// Add the declaration property/value pair.
+		$this->declarations[ $property ] = $value;
 	}
 
 	/**
@@ -81,29 +81,29 @@ public function add_declarations( $declarations ) {
 	}
 
 	/**
-	 * Get the styles array.
+	 * Get the declarations array.
 	 *
 	 * @return array
 	 */
-	public function get_styles() {
-		return $this->styles;
+	public function get_declarations() {
+		return $this->declarations;
 	}
 
 	/**
-	 * Get the CSS styles.
+	 * Filters and compiles the CSS declarations.
 	 *
-	 * @return string The CSS styles.
+	 * @return string The CSS declarations.
 	 */
-	public function get_styles_string() {
-		$styles_array = $this->get_styles();
-		$styles       = '';
-		foreach ( $styles_array as $property => $value ) {
-			$css = esc_html( safecss_filter_attr( "{$property}: {$value}" ) );
-			if ( $css ) {
-				$styles .= $css . '; ';
+	public function get_declarations_string() {
+		$declarations_array  = $this->get_declarations();
+		$declarations_output = '';
+		foreach ( $declarations_array as $property => $value ) {
+			$filtered_declaration = esc_html( safecss_filter_attr( "{$property}: {$value}" ) );
+			if ( $filtered_declaration ) {
+				$declarations_output .= $filtered_declaration . '; ';
 			}
 		}
-		return rtrim( $styles );
+		return rtrim( $declarations_output );
 	}
 
 	/**

diff --git a/packages/style-engine/class-wp-style-engine.php b/packages/style-engine/class-wp-style-engine.php
@@ -382,11 +382,11 @@ protected static function get_css_declarations( $style_value, $style_definition,
 	}
 
 	/**
-	 * Returns classname and CSS from a block styles object.
+	 * Returns classnames and CSS based on the values in a block attributes.styles object.
 	 * Return values are parsed based on the instructions in BLOCK_STYLE_DEFINITIONS_METADATA.
 	 *
-	 * @param array $block_styles An array of styles from a block's attributes.
-	 * @param array $options array(
+	 * @param array $block_styles Styles from a block's attributes 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`.
 	 * );.
@@ -396,7 +396,7 @@ protected static function get_css_declarations( $style_value, $style_definition,
 	 *     'classnames' => (string) Classnames separated by a space.
 	 * );
 	 */
-	public function generate( $block_styles, $options ) {
+	public function get_block_supports_styles( $block_styles, $options ) {
 		if ( empty( $block_styles ) || ! is_array( $block_styles ) ) {
 			return null;
 		}
@@ -428,7 +428,7 @@ public function generate( $block_styles, $options ) {
 
 		// The return object.
 		$styles_output = array();
-		$css           = $style_rules->get_styles_string();
+		$css           = $style_rules->get_declarations_string();
 
 		// Return css, if any.
 		if ( ! empty( $css ) ) {
@@ -496,30 +496,28 @@ protected static function get_individual_property_css_declarations( $style_value
 }
 
 /**
- * Global public interface method to WP_Style_Engine->generate.
- *
- * Returns an CSS ruleset.
- * Styles are bundled based on the instructions in BLOCK_STYLE_DEFINITIONS_METADATA.
+ * Global public interface method to WP_Style_Engine->get_block_supports_styles to generate block styles from a single block style object.
+ * See: https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/
  *
  * Example usage:
  *
- * $styles = wp_style_engine_generate( array( 'color' => array( 'text' => '#cccccc' ) ) );
- * // Returns `'color: #cccccc'`.
+ * $styles = wp_style_engine_get_block_supports_styles( array( 'color' => array( 'text' => '#cccccc' ) ) );
+ * // Returns `array( 'css' => 'color: #cccccc', 'classnames' => 'has-color' )`.
  *
  * @access public
  *
- * @param array $block_styles An array of styles from a block's attributes.
- * @param array $options An array of options to determine the output.
+ * @param array         $block_styles The value of a block's attributes.style.
+ * @param array<string> $options      An array of options to determine the output.
  *
- * @return array|null array(
+ * @return array<string>|null array(
  *     'styles'     => (string) A CSS ruleset formatted to be placed in an HTML `style` attribute or tag.
  *     'classnames' => (string) Classnames separated by a space.
  * );
  */
-function wp_style_engine_generate( $block_styles, $options = array() ) {
+function wp_style_engine_get_block_supports_styles( $block_styles, $options = array() ) {
 	if ( class_exists( 'WP_Style_Engine' ) ) {
 		$style_engine = WP_Style_Engine::get_instance();
-		return $style_engine->generate( $block_styles, $options );
+		return $style_engine->get_block_supports_styles( $block_styles, $options );
 	}
 	return null;
 }
diff --git a/packages/style-engine/phpunit/class-wp-style-engine-test.php b/packages/style-engine/phpunit/class-wp-style-engine-test.php
@@ -14,12 +14,16 @@
  */
 class WP_Style_Engine_Test extends WP_UnitTestCase {
 	/**
-	 * Tests generating styles and classnames based on various manifestations of the $block_styles argument.
+	 * Tests generating block styles and classnames based on various manifestations of the $block_styles argument.
 	 *
-	 * @dataProvider data_generate_styles_fixtures
+	 * @dataProvider data_generate_block_supports_styles_fixtures
+	 *
+	 * @param array  $block_styles    The incoming block styles object.
+	 * @param array  $options         Style engine options.
+	 * @param string $expected_output The expected output.
 	 */
-	function test_generate_styles( $block_styles, $options, $expected_output ) {
-		$generated_styles = wp_style_engine_generate( $block_styles, $options );
+	public function test_generate_block_supports_styles( $block_styles, $options, $expected_output ) {
+		$generated_styles = wp_style_engine_get_block_supports_styles( $block_styles, $options );
 		$this->assertSame( $expected_output, $generated_styles );
 	}
 
@@ -28,7 +32,7 @@ function test_generate_styles( $block_styles, $options, $expected_output ) {
 	 *
 	 * @return array
 	 */
-	public function data_generate_styles_fixtures() {
+	public function data_generate_block_supports_styles_fixtures() {
 		return array(
 			'default_return_value'                         => array(
 				'block_styles'    => array(),