gutenberg / build / scripts / style-engine / class-wp-style-engine-css-declarations-gutenberg.php

class-wp-style-engine-css-declarations-gutenberg.php in Gutenberg 23.6.0, at build/scripts/style-engine/class-wp-style-engine-css-declarations-gutenberg.php

232 lines 6.5 KB

Raw Download Zip

1	<?php
2	/**
3	* WP_Style_Engine_CSS_Declarations_Gutenberg
4	*
5	* Holds, sanitizes and prints CSS rules declarations
6	*
7	* @package gutenberg
8	*/
9
10	if ( ! class_exists( 'WP_Style_Engine_CSS_Declarations_Gutenberg' ) ) {
11
12	/**
13	* Holds, sanitizes, processes and prints CSS declarations for the Style Engine.
14	*
15	* @access private
16	*/
17	class WP_Style_Engine_CSS_Declarations_Gutenberg {
18	/**
19	* An array of CSS declarations (property => value pairs).
20	*
21	* @var array
22	*/
23	protected $declarations = array();
24
25	/**
26	* CSS declaration options keyed by property name.
27	*
28	* @var array
29	*/
30	protected $declaration_options = array();
31
32	/**
33	* Constructor for this object.
34	*
35	* If a `$declarations` array is passed, it will be used to populate
36	* the initial $declarations prop of the object by calling add_declarations().
37	*
38	* @param string[] $declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
39	*/
40	public function __construct( $declarations = array() ) {
41	$this->add_declarations( $declarations );
42	}
43
44	/**
45	* Adds a single declaration.
46	*
47	* @param string $property The CSS property.
48	* @param string $value The CSS value.
49	* @param array $options {
50	* Optional. An array of options. Default empty array.
51	*
52	* @type bool $important Whether to output the declaration with !important. Default false.
53	* }
54	*
55	* @return WP_Style_Engine_CSS_Declarations_Gutenberg Returns the object to allow chaining methods.
56	*/
57	public function add_declaration( $property, $value, $options = array() ) {
58	// Sanitizes the property.
59	$property = $this->sanitize_property( $property );
60	// Bails early if the property is empty.
61	if ( empty( $property ) ) {
62	return $this;
63	}
64
65	// Bail early if value is not a string. Prevents fatal errors from malformed block markup.
66	if ( ! is_string( $value ) ) {
67	return $this;
68	}
69	$value = trim( $value );
70	if ( '' === $value ) {
71	return $this;
72	}
73
74	$options = wp_parse_args(
75	$options,
76	array(
77	'important' => false,
78	)
79	);
80
81	$options = array_filter( $options );
82
83	// Adds the declaration property/value pair.
84	$this->declarations[ $property ] = $value;
85	if ( $options ) {
86	$this->declaration_options[ $property ] = $options;
87	} else {
88	unset( $this->declaration_options[ $property ] );
89	}
90
91	return $this;
92	}
93
94	/**
95	* Removes a single declaration.
96	*
97	* @param string $property The CSS property.
98	*
99	* @return WP_Style_Engine_CSS_Declarations_Gutenberg Returns the object to allow chaining methods.
100	*/
101	public function remove_declaration( $property ) {
102	unset( $this->declarations[ $property ] );
103	unset( $this->declaration_options[ $property ] );
104	return $this;
105	}
106
107	/**
108	* Adds multiple declarations.
109	*
110	* @param array $declarations An array of declarations.
111	*
112	* @return WP_Style_Engine_CSS_Declarations_Gutenberg Returns the object to allow chaining methods.
113	*/
114	public function add_declarations( $declarations ) {
115	foreach ( $declarations as $property => $value ) {
116	$this->add_declaration( $property, $value );
117	}
118	return $this;
119	}
120
121	/**
122	* Removes multiple declarations.
123	*
124	* @param array $properties An array of properties.
125	*
126	* @return WP_Style_Engine_CSS_Declarations_Gutenberg Returns the object to allow chaining methods.
127	*/
128	public function remove_declarations( $properties = array() ) {
129	foreach ( $properties as $property ) {
130	$this->remove_declaration( $property );
131	}
132	return $this;
133	}
134
135	/**
136	* Gets the declarations array.
137	*
138	* @return array
139	*/
140	public function get_declarations() {
141	return $this->declarations;
142	}
143
144	/**
145	* Gets declaration options keyed by property name.
146	*
147	* @return array
148	*/
149	public function get_declaration_options() {
150	return $this->declaration_options;
151	}
152
153	/**
154	* Filters a CSS property + value pair.
155	*
156	* @param string $property The CSS property.
157	* @param string $value The value to be filtered.
158	* @param string $spacer The spacer between the colon and the value. Defaults to an empty string.
159	* @param array $options {
160	* Optional. An array of options. Default empty array.
161	*
162	* @type bool $important Whether to output the declaration with !important. Default false.
163	* }
164	*
165	* @return string The filtered declaration or an empty string.
166	*/
167	protected static function filter_declaration( $property, $value, $spacer = '', $options = array() ) {
168	$filtered_value = wp_strip_all_tags( $value, true );
169
170	if ( '' !== $filtered_value ) {
171	$options = wp_parse_args(
172	$options,
173	array(
174	'important' => false,
175	)
176	);
177
178	$filtered_declaration = safecss_filter_attr( "{$property}:{$spacer}{$filtered_value}" );
179
180	// Only append !important in the presence of an option value and when sanitization returns a single declaration.
181	if ( true === $options['important'] && '' !== $filtered_declaration && ! str_contains( $filtered_declaration, ';' ) ) {
182	return "$filtered_declaration !important";
183	}
184
185	return $filtered_declaration;
186	}
187	return '';
188	}
189
190	/**
191	* Filters and compiles the CSS declarations.
192	*
193	* @param bool $should_prettify Whether to add spacing, new lines and indents.
194	* @param int $indent_count The number of tab indents to apply to the rule. Applies if `prettify` is `true`.
195	*
196	* @return string The CSS declarations.
197	*/
198	public function get_declarations_string( $should_prettify = false, $indent_count = 0 ) {
199	$declarations_array = $this->get_declarations();
200	$declarations_output = '';
201	$indent = $should_prettify ? str_repeat( "\t", $indent_count ) : '';
202	$suffix = $should_prettify ? ' ' : '';
203	$suffix = $should_prettify && $indent_count > 0 ? "\n" : $suffix;
204	$spacer = $should_prettify ? ' ' : '';
205
206	foreach ( $declarations_array as $property => $value ) {
207	$filtered_declaration = static::filter_declaration(
208	$property,
209	$value,
210	$spacer,
211	$this->declaration_options[ $property ] ?? array()
212	);
213	if ( $filtered_declaration ) {
214	$declarations_output .= "{$indent}{$filtered_declaration};$suffix";
215	}
216	}
217	return rtrim( $declarations_output );
218	}
219
220	/**
221	* Sanitizes property names.
222	*
223	* @param string $property The CSS property.
224	*
225	* @return string The sanitized property name.
226	*/
227	protected function sanitize_property( $property ) {
228	return sanitize_key( $property );
229	}
230	}
231	}
232