1<?php
2/**
3 * Dependencies API: Styles functions
4 *
5 * @since 2.6.0
6 *
7 * @package WordPress
8 * @subpackage Dependencies
9 */
10
11/**
12 * Initializes $wp_styles if it has not been set.
13 *
14 * @since 4.2.0
15 *
16 * @global WP_Styles $wp_styles
17 *
18 * @return WP_Styles WP_Styles instance.
19 */
20function wp_styles() {
21 global $wp_styles;
22
23 if ( ! ( $wp_styles instanceof WP_Styles ) ) {
24 $wp_styles = new WP_Styles();
25 }
26
27 return $wp_styles;
28}
29
30/**
31 * Displays styles that are in the $handles queue.
32 *
33 * Passing an empty array to $handles prints the queue,
34 * passing an array with one string prints that style,
35 * and passing an array of strings prints those styles.
36 *
37 * @since 2.6.0
38 *
39 * @global WP_Styles $wp_styles The WP_Styles object for printing styles.
40 *
41 * @param string|bool|array $handles Styles to be printed. Default 'false'.
42 * @return string[] On success, an array of handles of processed WP_Dependencies items; otherwise, an empty array.
43 */
44function wp_print_styles( $handles = false ) {
45 global $wp_styles;
46
47 if ( '' === $handles ) { // For 'wp_head'.
48 $handles = false;
49 }
50
51 if ( ! $handles ) {
52 /**
53 * Fires before styles in the $handles queue are printed.
54 *
55 * @since 2.6.0
56 */
57 do_action( 'wp_print_styles' );
58 }
59
60 _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ );
61
62 if ( ! ( $wp_styles instanceof WP_Styles ) ) {
63 if ( ! $handles ) {
64 return array(); // No need to instantiate if nothing is there.
65 }
66 }
67
68 return wp_styles()->do_items( $handles );
69}
70
71/**
72 * Adds extra CSS styles to a registered stylesheet.
73 *
74 * Styles will only be added if the stylesheet is already in the queue.
75 * Accepts a string $data containing the CSS. If two or more CSS code blocks
76 * are added to the same stylesheet $handle, they will be printed in the order
77 * they were added, i.e. the latter added styles can redeclare the previous.
78 *
79 * @see WP_Styles::add_inline_style()
80 *
81 * @since 3.3.0
82 *
83 * @param string $handle Name of the stylesheet to add the extra styles to.
84 * @param string $data String containing the CSS styles to be added.
85 * @return bool True on success, false on failure.
86 */
87function wp_add_inline_style( $handle, $data ) {
88 _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle );
89
90 if ( false !== stripos( $data, '</style>' ) ) {
91 _doing_it_wrong(
92 __FUNCTION__,
93 sprintf(
94 /* translators: 1: <style>, 2: wp_add_inline_style() */
95 __( 'Do not pass %1$s tags to %2$s.' ),
96 '<code><style></code>',
97 '<code>wp_add_inline_style()</code>'
98 ),
99 '3.7.0'
100 );
101 $data = trim( preg_replace( '#<style[^>]*>(.*)</style>#is', '$1', $data ) );
102 }
103
104 return wp_styles()->add_inline_style( $handle, $data );
105}
106
107/**
108 * Registers a CSS stylesheet.
109 *
110 * @see WP_Dependencies::add()
111 * @link https://www.w3.org/TR/CSS2/media.html#media-types List of CSS media types.
112 *
113 * @since 2.6.0
114 * @since 4.3.0 A return value was added.
115 *
116 * @param string $handle Name of the stylesheet. Should be unique.
117 * @param string|false $src Full URL of the stylesheet, or path of the stylesheet relative to the WordPress root directory.
118 * If source is set to false, stylesheet is an alias of other stylesheets it depends on.
119 * @param string[] $deps Optional. An array of registered stylesheet handles this stylesheet depends on. Default empty array.
120 * @param string|bool|null $ver Optional. String specifying stylesheet version number, if it has one, which is added to the URL
121 * as a query string for cache busting purposes. If version is set to false, a version
122 * number is automatically added equal to current installed WordPress version.
123 * If set to null, no version is added.
124 * @param string $media Optional. The media for which this stylesheet has been defined.
125 * Default 'all'. Accepts media types like 'all', 'print' and 'screen', or media queries like
126 * '(orientation: portrait)' and '(max-width: 640px)'.
127 * @return bool Whether the style has been registered. True on success, false on failure.
128 */
129function wp_register_style( $handle, $src, $deps = array(), $ver = false, $media = 'all' ) {
130 _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle );
131
132 return wp_styles()->add( $handle, $src, $deps, $ver, $media );
133}
134
135/**
136 * Removes a registered stylesheet.
137 *
138 * @see WP_Dependencies::remove()
139 *
140 * @since 2.1.0
141 *
142 * @param string $handle Name of the stylesheet to be removed.
143 */
144function wp_deregister_style( $handle ) {
145 _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle );
146
147 wp_styles()->remove( $handle );
148}
149
150/**
151 * Enqueues a CSS stylesheet.
152 *
153 * Registers the style if source provided (does NOT overwrite) and enqueues.
154 *
155 * @see WP_Dependencies::add()
156 * @see WP_Dependencies::enqueue()
157 * @link https://www.w3.org/TR/CSS2/media.html#media-types List of CSS media types.
158 *
159 * @since 2.6.0
160 *
161 * @param string $handle Name of the stylesheet. Should be unique.
162 * @param string $src Full URL of the stylesheet, or path of the stylesheet relative to the WordPress root directory.
163 * Default empty.
164 * @param string[] $deps Optional. An array of registered stylesheet handles this stylesheet depends on. Default empty array.
165 * @param string|bool|null $ver Optional. String specifying stylesheet version number, if it has one, which is added to the URL
166 * as a query string for cache busting purposes. If version is set to false, a version
167 * number is automatically added equal to current installed WordPress version.
168 * If set to null, no version is added.
169 * @param string $media Optional. The media for which this stylesheet has been defined.
170 * Default 'all'. Accepts media types like 'all', 'print' and 'screen', or media queries like
171 * '(orientation: portrait)' and '(max-width: 640px)'.
172 */
173function wp_enqueue_style( $handle, $src = '', $deps = array(), $ver = false, $media = 'all' ) {
174 _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle );
175
176 $wp_styles = wp_styles();
177
178 if ( $src ) {
179 $_handle = explode( '?', $handle );
180 $wp_styles->add( $_handle[0], $src, $deps, $ver, $media );
181 }
182
183 $wp_styles->enqueue( $handle );
184}
185
186/**
187 * Removes a previously enqueued CSS stylesheet.
188 *
189 * @see WP_Dependencies::dequeue()
190 *
191 * @since 3.1.0
192 *
193 * @param string $handle Name of the stylesheet to be removed.
194 */
195function wp_dequeue_style( $handle ) {
196 _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle );
197
198 wp_styles()->dequeue( $handle );
199}
200
201/**
202 * Checks whether a CSS stylesheet has been added to the queue.
203 *
204 * @since 2.8.0
205 *
206 * @param string $handle Name of the stylesheet.
207 * @param string $status Optional. Status of the stylesheet to check. Default 'enqueued'.
208 * Accepts 'enqueued', 'registered', 'queue', 'to_do', and 'done'.
209 * @return bool Whether style is queued.
210 */
211function wp_style_is( $handle, $status = 'enqueued' ) {
212 _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle );
213
214 return (bool) wp_styles()->query( $handle, $status );
215}
216
217/**
218 * Adds metadata to a CSS stylesheet.
219 *
220 * Works only if the stylesheet has already been registered.
221 *
222 * Possible values for $key and $value:
223 * 'rtl' bool|string To declare an RTL stylesheet.
224 * 'suffix' string Optional suffix, used in combination with RTL.
225 * 'alt' bool For rel="alternate stylesheet".
226 * 'title' string For preferred/alternate stylesheets.
227 * 'path' string The absolute path to a stylesheet. Stylesheet will
228 * load inline when 'path' is set.
229 *
230 * @see WP_Dependencies::add_data()
231 *
232 * @since 3.6.0
233 * @since 5.8.0 Added 'path' as an official value for $key.
234 * See {@see wp_maybe_inline_styles()}.
235 * @since 6.9.0 'conditional' value changed. If the 'conditional' parameter is present
236 * the stylesheet will be ignored.
237 *
238 * @param string $handle Name of the stylesheet.
239 * @param string $key Name of data point for which we're storing a value.
240 * Accepts 'rtl' and 'suffix', 'alt', 'title' and 'path'.
241 * @param mixed $value String containing the CSS data to be added.
242 * @return bool True on success, false on failure.
243 */
244function wp_style_add_data( $handle, $key, $value ) {
245 return wp_styles()->add_data( $handle, $key, $value );
246}
247