[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       *
  85       * @param string[]|WP_Style_Engine_CSS_Declarations $declarations An array of declarations (property => value pairs),
  86       *                                                                or a WP_Style_Engine_CSS_Declarations object.
  87       * @return WP_Style_Engine_CSS_Rule Returns the object to allow chaining of methods.
  88       */
  89  	public function add_declarations( $declarations ) {
  90          $is_declarations_object = ! is_array( $declarations );
  91          $declarations_array     = $is_declarations_object ? $declarations->get_declarations() : $declarations;
  92  
  93          if ( null === $this->declarations ) {
  94              if ( $is_declarations_object ) {
  95                  $this->declarations = $declarations;
  96                  return $this;
  97              }
  98              $this->declarations = new WP_Style_Engine_CSS_Declarations( $declarations_array );
  99          }
 100          $this->declarations->add_declarations( $declarations_array );
 101  
 102          return $this;
 103      }
 104  
 105      /**
 106       * Sets the rules group.
 107       *
 108       * @since 6.6.0
 109       *
 110       * @param string $rules_group A parent CSS selector in the case of nested CSS, or a CSS nested @rule,
 111       *                            such as `@media (min-width: 80rem)` or `@layer module`.
 112       * @return WP_Style_Engine_CSS_Rule Returns the object to allow chaining of methods.
 113       */
 114  	public function set_rules_group( $rules_group ) {
 115          $this->rules_group = $rules_group;
 116          return $this;
 117      }
 118  
 119      /**
 120       * Gets the rules group.
 121       *
 122       * @since 6.6.0
 123       *
 124       * @return string
 125       */
 126  	public function get_rules_group() {
 127          return $this->rules_group;
 128      }
 129  
 130      /**
 131       * Gets the declarations object.
 132       *
 133       * @since 6.1.0
 134       *
 135       * @return WP_Style_Engine_CSS_Declarations The declarations object.
 136       */
 137  	public function get_declarations() {
 138          return $this->declarations;
 139      }
 140  
 141      /**
 142       * Gets the full selector.
 143       *
 144       * @since 6.1.0
 145       *
 146       * @return string
 147       */
 148  	public function get_selector() {
 149          return $this->selector;
 150      }
 151  
 152      /**
 153       * Gets the CSS.
 154       *
 155       * @since 6.1.0
 156       * @since 6.6.0 Added support for nested CSS with rules groups.
 157       *
 158       * @param bool $should_prettify Optional. Whether to add spacing, new lines and indents.
 159       *                              Default false.
 160       * @param int  $indent_count    Optional. The number of tab indents to apply to the rule.
 161       *                              Applies if `prettify` is `true`. Default 0.
 162       * @return string
 163       */
 164  	public function get_css( $should_prettify = false, $indent_count = 0 ) {
 165          $rule_indent                = $should_prettify ? str_repeat( "\t", $indent_count ) : '';
 166          $nested_rule_indent         = $should_prettify ? str_repeat( "\t", $indent_count + 1 ) : '';
 167          $declarations_indent        = $should_prettify ? $indent_count + 1 : 0;
 168          $nested_declarations_indent = $should_prettify ? $indent_count + 2 : 0;
 169          $suffix                     = $should_prettify ? "\n" : '';
 170          $spacer                     = $should_prettify ? ' ' : '';
 171          // Trims any multiple selectors strings.
 172          $selector         = $should_prettify ? implode( ',', array_map( 'trim', explode( ',', $this->get_selector() ) ) ) : $this->get_selector();
 173          $selector         = $should_prettify ? str_replace( array( ',' ), ",\n", $selector ) : $selector;
 174          $rules_group      = $this->get_rules_group();
 175          $has_rules_group  = ! empty( $rules_group );
 176          $css_declarations = $this->declarations->get_declarations_string( $should_prettify, $has_rules_group ? $nested_declarations_indent : $declarations_indent );
 177  
 178          if ( empty( $css_declarations ) ) {
 179              return '';
 180          }
 181  
 182          if ( $has_rules_group ) {
 183              $selector = "{$rule_indent}{$rules_group}{$spacer}{{$suffix}{$nested_rule_indent}{$selector}{$spacer}{{$suffix}{$css_declarations}{$suffix}{$nested_rule_indent}}{$suffix}{$rule_indent}}";
 184              return $selector;
 185          }
 186  
 187          return "{$rule_indent}{$selector}{$spacer}{{$suffix}{$css_declarations}{$suffix}{$rule_indent}}";
 188      }
 189  }