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]
18class 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}
190