|
1 <?php |
|
2 /** |
|
3 * Style Engine: WP_Style_Engine_CSS_Declarations class |
|
4 * |
|
5 * @package WordPress |
|
6 * @subpackage StyleEngine |
|
7 * @since 6.1.0 |
|
8 */ |
|
9 |
|
10 /** |
|
11 * Core class used for style engine CSS declarations. |
|
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_Declarations { |
|
19 |
|
20 /** |
|
21 * An array of CSS declarations (property => value pairs). |
|
22 * |
|
23 * @since 6.1.0 |
|
24 * |
|
25 * @var string[] |
|
26 */ |
|
27 protected $declarations = array(); |
|
28 |
|
29 /** |
|
30 * Constructor for this object. |
|
31 * |
|
32 * If a `$declarations` array is passed, it will be used to populate |
|
33 * the initial `$declarations` prop of the object by calling add_declarations(). |
|
34 * |
|
35 * @since 6.1.0 |
|
36 * |
|
37 * @param string[] $declarations Optional. An associative array of CSS definitions, |
|
38 * e.g. `array( "$property" => "$value", "$property" => "$value" )`. |
|
39 * Default empty array. |
|
40 */ |
|
41 public function __construct( $declarations = array() ) { |
|
42 $this->add_declarations( $declarations ); |
|
43 } |
|
44 |
|
45 /** |
|
46 * Adds a single declaration. |
|
47 * |
|
48 * @since 6.1.0 |
|
49 * |
|
50 * @param string $property The CSS property. |
|
51 * @param string $value The CSS value. |
|
52 * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods. |
|
53 */ |
|
54 public function add_declaration( $property, $value ) { |
|
55 // Sanitizes the property. |
|
56 $property = $this->sanitize_property( $property ); |
|
57 // Bails early if the property is empty. |
|
58 if ( empty( $property ) ) { |
|
59 return $this; |
|
60 } |
|
61 |
|
62 // Trims the value. If empty, bail early. |
|
63 $value = trim( $value ); |
|
64 if ( '' === $value ) { |
|
65 return $this; |
|
66 } |
|
67 |
|
68 // Adds the declaration property/value pair. |
|
69 $this->declarations[ $property ] = $value; |
|
70 |
|
71 return $this; |
|
72 } |
|
73 |
|
74 /** |
|
75 * Removes a single declaration. |
|
76 * |
|
77 * @since 6.1.0 |
|
78 * |
|
79 * @param string $property The CSS property. |
|
80 * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods. |
|
81 */ |
|
82 public function remove_declaration( $property ) { |
|
83 unset( $this->declarations[ $property ] ); |
|
84 return $this; |
|
85 } |
|
86 |
|
87 /** |
|
88 * Adds multiple declarations. |
|
89 * |
|
90 * @since 6.1.0 |
|
91 * |
|
92 * @param string[] $declarations An array of declarations. |
|
93 * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods. |
|
94 */ |
|
95 public function add_declarations( $declarations ) { |
|
96 foreach ( $declarations as $property => $value ) { |
|
97 $this->add_declaration( $property, $value ); |
|
98 } |
|
99 return $this; |
|
100 } |
|
101 |
|
102 /** |
|
103 * Removes multiple declarations. |
|
104 * |
|
105 * @since 6.1.0 |
|
106 * |
|
107 * @param string[] $properties Optional. An array of properties. Default empty array. |
|
108 * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods. |
|
109 */ |
|
110 public function remove_declarations( $properties = array() ) { |
|
111 foreach ( $properties as $property ) { |
|
112 $this->remove_declaration( $property ); |
|
113 } |
|
114 return $this; |
|
115 } |
|
116 |
|
117 /** |
|
118 * Gets the declarations array. |
|
119 * |
|
120 * @since 6.1.0 |
|
121 * |
|
122 * @return string[] The declarations array. |
|
123 */ |
|
124 public function get_declarations() { |
|
125 return $this->declarations; |
|
126 } |
|
127 |
|
128 /** |
|
129 * Filters a CSS property + value pair. |
|
130 * |
|
131 * @since 6.1.0 |
|
132 * |
|
133 * @param string $property The CSS property. |
|
134 * @param string $value The value to be filtered. |
|
135 * @param string $spacer Optional. The spacer between the colon and the value. |
|
136 * Default empty string. |
|
137 * @return string The filtered declaration or an empty string. |
|
138 */ |
|
139 protected static function filter_declaration( $property, $value, $spacer = '' ) { |
|
140 $filtered_value = wp_strip_all_tags( $value, true ); |
|
141 if ( '' !== $filtered_value ) { |
|
142 return safecss_filter_attr( "{$property}:{$spacer}{$filtered_value}" ); |
|
143 } |
|
144 return ''; |
|
145 } |
|
146 |
|
147 /** |
|
148 * Filters and compiles the CSS declarations. |
|
149 * |
|
150 * @since 6.1.0 |
|
151 * |
|
152 * @param bool $should_prettify Optional. Whether to add spacing, new lines and indents. |
|
153 * Default false. |
|
154 * @param int $indent_count Optional. The number of tab indents to apply to the rule. |
|
155 * Applies if `prettify` is `true`. Default 0. |
|
156 * @return string The CSS declarations. |
|
157 */ |
|
158 public function get_declarations_string( $should_prettify = false, $indent_count = 0 ) { |
|
159 $declarations_array = $this->get_declarations(); |
|
160 $declarations_output = ''; |
|
161 $indent = $should_prettify ? str_repeat( "\t", $indent_count ) : ''; |
|
162 $suffix = $should_prettify ? ' ' : ''; |
|
163 $suffix = $should_prettify && $indent_count > 0 ? "\n" : $suffix; |
|
164 $spacer = $should_prettify ? ' ' : ''; |
|
165 |
|
166 foreach ( $declarations_array as $property => $value ) { |
|
167 $filtered_declaration = static::filter_declaration( $property, $value, $spacer ); |
|
168 if ( $filtered_declaration ) { |
|
169 $declarations_output .= "{$indent}{$filtered_declaration};$suffix"; |
|
170 } |
|
171 } |
|
172 |
|
173 return rtrim( $declarations_output ); |
|
174 } |
|
175 |
|
176 /** |
|
177 * Sanitizes property names. |
|
178 * |
|
179 * @since 6.1.0 |
|
180 * |
|
181 * @param string $property The CSS property. |
|
182 * @return string The sanitized property name. |
|
183 */ |
|
184 protected function sanitize_property( $property ) { |
|
185 return sanitize_key( $property ); |
|
186 } |
|
187 } |