[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Style engine: Public functions
   4   *
   5   * This file contains a variety of public functions developers can use to interact with
   6   * the Style Engine API.
   7   *
   8   * @package WordPress
   9   * @subpackage StyleEngine
  10   * @since 6.1.0
  11   */
  12  
  13  /**
  14   * Global public interface method to generate styles from a single style object,
  15   * e.g. the value of a block's attributes.style object or the top level styles in theme.json.
  16   *
  17   * Example usage:
  18   *
  19   *     $styles = wp_style_engine_get_styles(
  20   *         array(
  21   *             'color' => array( 'text' => '#cccccc' ),
  22   *         )
  23   *     );
  24   *
  25   * Returns:
  26   *
  27   *     array(
  28   *         'css'          => 'color: #cccccc',
  29   *         'declarations' => array( 'color' => '#cccccc' ),
  30   *         'classnames'   => 'has-color',
  31   *     )
  32   *
  33   * @since 6.1.0
  34   *
  35   * @see https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-living/#styles
  36   * @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/
  37   *
  38   * @param array $block_styles The style object.
  39   * @param array $options {
  40   *     Optional. An array of options. Default empty array.
  41   *
  42   *     @type string|null $context                    An identifier describing the origin of the style object,
  43   *                                                   e.g. 'block-supports' or 'global-styles'. Default null.
  44   *                                                   When set, the style engine will attempt to store the CSS rules,
  45   *                                                   where a selector is also passed.
  46   *     @type bool        $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns,
  47   *                                                   e.g. `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`,
  48   *                                                   to `var( --wp--preset--* )` values. Default false.
  49   *     @type string      $selector                   Optional. When a selector is passed,
  50   *                                                   the value of `$css` in the return value will comprise
  51   *                                                   a full CSS rule `$selector { ...$css_declarations }`,
  52   *                                                   otherwise, the value will be a concatenated string
  53   *                                                   of CSS declarations.
  54   * }
  55   * @return array {
  56   *     @type string   $css          A CSS ruleset or declarations block
  57   *                                  formatted to be placed in an HTML `style` attribute or tag.
  58   *     @type string[] $declarations An associative array of CSS definitions,
  59   *                                  e.g. `array( "$property" => "$value", "$property" => "$value" )`.
  60   *     @type string   $classnames   Classnames separated by a space.
  61   * }
  62   */
  63  function wp_style_engine_get_styles( $block_styles, $options = array() ) {
  64      $options = wp_parse_args(
  65          $options,
  66          array(
  67              'selector'                   => null,
  68              'context'                    => null,
  69              'convert_vars_to_classnames' => false,
  70          )
  71      );
  72  
  73      $parsed_styles = WP_Style_Engine::parse_block_styles( $block_styles, $options );
  74  
  75      // Output.
  76      $styles_output = array();
  77  
  78      if ( ! empty( $parsed_styles['declarations'] ) ) {
  79          $styles_output['css']          = WP_Style_Engine::compile_css( $parsed_styles['declarations'], $options['selector'] );
  80          $styles_output['declarations'] = $parsed_styles['declarations'];
  81          if ( ! empty( $options['context'] ) ) {
  82              WP_Style_Engine::store_css_rule( $options['context'], $options['selector'], $parsed_styles['declarations'] );
  83          }
  84      }
  85  
  86      if ( ! empty( $parsed_styles['classnames'] ) ) {
  87          $styles_output['classnames'] = implode( ' ', array_unique( $parsed_styles['classnames'] ) );
  88      }
  89  
  90      return array_filter( $styles_output );
  91  }
  92  
  93  /**
  94   * Returns compiled CSS from a collection of selectors and declarations.
  95   * Useful for returning a compiled stylesheet from any collection of CSS selector + declarations.
  96   *
  97   * Example usage:
  98   *
  99   *     $css_rules = array(
 100   *         array(
 101   *             'selector'     => '.elephant-are-cool',
 102   *             'declarations' => array(
 103   *                 'color' => 'gray',
 104   *                 'width' => '3em',
 105   *             ),
 106   *         ),
 107   *     );
 108   *
 109   *     $css = wp_style_engine_get_stylesheet_from_css_rules( $css_rules );
 110   *
 111   * Returns:
 112   *
 113   *     .elephant-are-cool{color:gray;width:3em}
 114   *
 115   * @since 6.1.0
 116   * @since 6.6.0 Added support for `$rules_group` in the `$css_rules` array.
 117   * @since 7.1.0 Extended `declarations` in `$css_rules` array to accept `WP_Style_Engine_CSS_Declarations` object.
 118   *
 119   * @param array $css_rules {
 120   *     Required. A collection of CSS rules.
 121   *
 122   *     @type array ...$0 {
 123   *         @type string                                    $rules_group  A parent CSS selector in the case of nested CSS,
 124   *                                                                       or a CSS nested @rule, such as `@media (min-width: 80rem)` or `@layer module`.
 125   *         @type string                                    $selector     A CSS selector.
 126   *         @type string[]|WP_Style_Engine_CSS_Declarations $declarations An associative array of CSS definitions,
 127   *                                                                       e.g. `array( "$property" => "$value", "$property" => "$value" )`,
 128   *                                                                       or a WP_Style_Engine_CSS_Declarations object.
 129   *     }
 130   * }
 131   * @param array $options {
 132   *     Optional. An array of options. Default empty array.
 133   *
 134   *     @type string|null $context  An identifier describing the origin of the style object,
 135   *                                 e.g. 'block-supports' or 'global-styles'. Default 'block-supports'.
 136   *                                 When set, the style engine will attempt to store the CSS rules.
 137   *     @type bool        $optimize Whether to optimize the CSS output, e.g. combine rules.
 138   *                                 Default false.
 139   *     @type bool        $prettify Whether to add new lines and indents to output.
 140   *                                 Defaults to whether the `SCRIPT_DEBUG` constant is defined.
 141   * }
 142   * @return string A string of compiled CSS declarations, or empty string.
 143   */
 144  function wp_style_engine_get_stylesheet_from_css_rules( $css_rules, $options = array() ) {
 145      if ( empty( $css_rules ) ) {
 146          return '';
 147      }
 148  
 149      $options = wp_parse_args(
 150          $options,
 151          array(
 152              'context' => null,
 153          )
 154      );
 155  
 156      $css_rule_objects = array();
 157      foreach ( $css_rules as $css_rule ) {
 158          $declarations = $css_rule['declarations'] ?? null;
 159          if (
 160              empty( $css_rule['selector'] ) ||
 161              empty( $declarations ) ||
 162              ( ! is_array( $declarations ) && ! $declarations instanceof WP_Style_Engine_CSS_Declarations )
 163          ) {
 164              continue;
 165          }
 166  
 167          $rules_group = $css_rule['rules_group'] ?? null;
 168          if ( ! empty( $options['context'] ) ) {
 169              WP_Style_Engine::store_css_rule( $options['context'], $css_rule['selector'], $declarations, $rules_group );
 170          }
 171  
 172          $css_rule_objects[] = new WP_Style_Engine_CSS_Rule( $css_rule['selector'], $declarations, $rules_group );
 173      }
 174  
 175      if ( empty( $css_rule_objects ) ) {
 176          return '';
 177      }
 178  
 179      return WP_Style_Engine::compile_stylesheet_from_css_rules( $css_rule_objects, $options );
 180  }
 181  
 182  /**
 183   * Returns compiled CSS from a store, if found.
 184   *
 185   * @since 6.1.0
 186   *
 187   * @param string $context A valid context name, corresponding to an existing store key.
 188   * @param array  $options {
 189   *     Optional. An array of options. Default empty array.
 190   *
 191   *     @type bool $optimize Whether to optimize the CSS output, e.g. combine rules.
 192   *                          Default false.
 193   *     @type bool $prettify Whether to add new lines and indents to output.
 194   *                          Defaults to whether the `SCRIPT_DEBUG` constant is defined.
 195   * }
 196   * @return string A compiled CSS string.
 197   */
 198  function wp_style_engine_get_stylesheet_from_context( $context, $options = array() ) {
 199      return WP_Style_Engine::compile_stylesheet_from_css_rules( WP_Style_Engine::get_store( $context )->get_all_rules(), $options );
 200  }