[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Style Engine: WP_Style_Engine_CSS_Rule class
   4   *
   5   * @package WordPress
   6   * @subpackage StyleEngine
   7   * @since 6.1.0
   8   */
   9  
  10  /**
  11   * Core class used for style engine CSS rules.
  12   *
  13   * Holds, sanitizes, processes, and prints CSS declarations for the style engine.
  14   *
  15   * @since 6.1.0
  16   */
  17  #[AllowDynamicProperties]
  18  class WP_Style_Engine_CSS_Rule {
  19  
  20      /**
  21       * The selector.
  22       *
  23       * @since 6.1.0
  24       * @var string
  25       */
  26      protected $selector;
  27  
  28      /**
  29       * The selector declarations.
  30       *
  31       * Contains a WP_Style_Engine_CSS_Declarations object.
  32       *
  33       * @since 6.1.0
  34       * @var WP_Style_Engine_CSS_Declarations
  35       */
  36      protected $declarations;
  37  
  38      /**
  39       * A parent CSS selector in the case of nested CSS, or a CSS nested @rule,
  40       * such as `@media (min-width: 80rem)` or `@layer module`.
  41       *
  42       * @since 6.6.0
  43       * @var string
  44       */
  45      protected $rules_group;
  46  
  47      /**
  48       * Constructor.
  49       *
  50       * @since 6.1.0
  51       * @since 6.6.0 Added the `$rules_group` parameter.
  52       *
  53       * @param string                                    $selector     Optional. The CSS selector. Default empty string.
  54       * @param string[]|WP_Style_Engine_CSS_Declarations $declarations Optional. An associative array of CSS definitions,
  55       *                                                                e.g. `array( "$property" => "$value", "$property" => "$value" )`,
  56       *                                                                or a WP_Style_Engine_CSS_Declarations object.
  57       *                                                                Default empty array.
  58       * @param string                                    $rules_group  A parent CSS selector in the case of nested CSS, or a CSS nested @rule,
  59       *                                                                such as `@media (min-width: 80rem)` or `@layer module`.
  60       */
  61  	public function __construct( $selector = '', $declarations = array(), $rules_group = '' ) {
  62          $this->set_selector( $selector );
  63          $this->add_declarations( $declarations );
  64          $this->set_rules_group( $rules_group );
  65      }
  66  
  67      /**
  68       * Sets the selector.
  69       *
  70       * @since 6.1.0
  71       *
  72       * @param string $selector The CSS selector.
  73       * @return WP_Style_Engine_CSS_Rule Returns the object to allow chaining of methods.
  74       */
  75  	public function set_selector( $selector ) {
  76          $this->selector = $selector;
  77          return $this;
  78      }
  79  
  80      /**
  81       * Sets the declarations.
  82       *
  83       * @since 6.1.0
  84       * @since 7.1.0 Preserves declaration options when declarations are provided as a `WP_Style_Engine_CSS_Declarations` object.
  85       *
  86       * @param string[]|WP_Style_Engine_CSS_Declarations $declarations An array of declarations (property => value pairs),
  87       *                                                                or a WP_Style_Engine_CSS_Declarations object.
  88       * @return WP_Style_Engine_CSS_Rule Returns the object to allow chaining of methods.
  89       */
  90  	public function add_declarations( $declarations ) {
  91          $is_declarations_object = ! is_array( $declarations );
  92          $declarations_array     = $is_declarations_object ? $declarations->get_declarations() : $declarations;
  93          $declaration_options    = $is_declarations_object ? $declarations->get_declaration_options() : array();
  94  
  95          if ( null === $this->declarations ) {
  96              if ( $is_declarations_object ) {
  97                  $this->declarations = $declarations;
  98                  return $this;
  99              }
 100              $this->declarations = new WP_Style_Engine_CSS_Declarations();
 101          }
 102  
 103          foreach ( $declarations_array as $property => $value ) {
 104              $this->declarations->add_declaration(
 105                  $property,
 106                  $value,
 107                  $declaration_options[ $property ] ?? array()
 108              );
 109          }
 110  
 111          return $this;
 112      }
 113  
 114      /**
 115       * Sets the rules group.
 116       *
 117       * @since 6.6.0
 118       *
 119       * @param string $rules_group A parent CSS selector in the case of nested CSS, or a CSS nested @rule,
 120       *                            such as `@media (min-width: 80rem)` or `@layer module`.
 121       * @return WP_Style_Engine_CSS_Rule Returns the object to allow chaining of methods.
 122       */
 123  	public function set_rules_group( $rules_group ) {
 124          $this->rules_group = $rules_group;
 125          return $this;
 126      }
 127  
 128      /**
 129       * Gets the rules group.
 130       *
 131       * @since 6.6.0
 132       *
 133       * @return string
 134       */
 135  	public function get_rules_group() {
 136          return $this->rules_group;
 137      }
 138  
 139      /**
 140       * Gets the declarations object.
 141       *
 142       * @since 6.1.0
 143       *
 144       * @return WP_Style_Engine_CSS_Declarations The declarations object.
 145       */
 146  	public function get_declarations() {
 147          return $this->declarations;
 148      }
 149  
 150      /**
 151       * Gets the full selector.
 152       *
 153       * @since 6.1.0
 154       *
 155       * @return string
 156       */
 157  	public function get_selector() {
 158          return $this->selector;
 159      }
 160  
 161      /**
 162       * Gets the CSS.
 163       *
 164       * @since 6.1.0
 165       * @since 6.6.0 Added support for nested CSS with rules groups.
 166       *
 167       * @param bool $should_prettify Optional. Whether to add spacing, new lines and indents.
 168       *                              Default false.
 169       * @param int  $indent_count    Optional. The number of tab indents to apply to the rule.
 170       *                              Applies if `prettify` is `true`. Default 0.
 171       * @return string
 172       */
 173  	public function get_css( $should_prettify = false, $indent_count = 0 ) {
 174          $rule_indent                = $should_prettify ? str_repeat( "\t", $indent_count ) : '';
 175          $nested_rule_indent         = $should_prettify ? str_repeat( "\t", $indent_count + 1 ) : '';
 176          $declarations_indent        = $should_prettify ? $indent_count + 1 : 0;
 177          $nested_declarations_indent = $should_prettify ? $indent_count + 2 : 0;
 178          $suffix                     = $should_prettify ? "\n" : '';
 179          $spacer                     = $should_prettify ? ' ' : '';
 180          // Trims any multiple selectors strings.
 181          $selector         = $should_prettify ? implode( ',', array_map( 'trim', explode( ',', $this->get_selector() ) ) ) : $this->get_selector();
 182          $selector         = $should_prettify ? str_replace( array( ',' ), ",\n", $selector ) : $selector;
 183          $rules_group      = $this->get_rules_group();
 184          $has_rules_group  = ! empty( $rules_group );
 185          $css_declarations = $this->declarations->get_declarations_string( $should_prettify, $has_rules_group ? $nested_declarations_indent : $declarations_indent );
 186  
 187          if ( empty( $css_declarations ) ) {
 188              return '';
 189          }
 190  
 191          if ( $has_rules_group ) {
 192              $selector = "{$rule_indent}{$rules_group}{$spacer}{{$suffix}{$nested_rule_indent}{$selector}{$spacer}{{$suffix}{$css_declarations}{$suffix}{$nested_rule_indent}}{$suffix}{$rule_indent}}";
 193              return $selector;
 194          }
 195  
 196          return "{$rule_indent}{$selector}{$spacer}{{$suffix}{$css_declarations}{$suffix}{$rule_indent}}";
 197      }
 198  }