gutenberg / lib / widgets-api.php

widgets-api.php in Gutenberg 11.2.1, at lib/widgets-api.php

270 lines 6.8 KB

Raw Download Zip

1	<?php
2	/**
3	* Functions for working with widgets in WordPress. These should ultimately live
4	* in wp-includes/widgets.php, wp-admin/includes/widgets.php, etc. when merged
5	* to Core.
6	*
7	* @package gutenberg
8	*/
9
10	if ( ! function_exists( 'wp_assign_widget_to_sidebar' ) ) {
11	/**
12	* Assigns a widget to the given sidebar.
13	*
14	* Can be removed when minimum WordPress version is 5.8.
15	*
16	* @since 10.2.0
17	*
18	* @param string $widget_id The widget id to assign.
19	* @param string $sidebar_id The sidebar id to assign to. If empty, the widget won't be added to any sidebar.
20	*/
21	function wp_assign_widget_to_sidebar( $widget_id, $sidebar_id ) {
22	$sidebars = wp_get_sidebars_widgets();
23
24	foreach ( $sidebars as $maybe_sidebar_id => $widgets ) {
25	foreach ( $widgets as $i => $maybe_widget_id ) {
26	if ( $widget_id === $maybe_widget_id && $sidebar_id !== $maybe_sidebar_id ) {
27	unset( $sidebars[ $maybe_sidebar_id ][ $i ] );
28	// We could technically break 2 here, but continue looping in case the id is duplicated.
29	continue 2;
30	}
31	}
32	}
33
34	if ( $sidebar_id ) {
35	$sidebars[ $sidebar_id ][] = $widget_id;
36	}
37
38	wp_set_sidebars_widgets( $sidebars );
39	}
40	}
41
42	if ( ! function_exists( 'wp_find_widgets_sidebar' ) ) {
43	/**
44	* Finds the sidebar that a given widget belongs to.
45	*
46	* Can be removed when minimum WordPress version is 5.8.
47	*
48	* @since 10.3.0
49	*
50	* @param string $widget_id The widget id to look for.
51	* @return string\|null The found sidebar's id, or null if it was not found.
52	*/
53	function wp_find_widgets_sidebar( $widget_id ) {
54	foreach ( wp_get_sidebars_widgets() as $sidebar_id => $widget_ids ) {
55	foreach ( $widget_ids as $maybe_widget_id ) {
56	if ( $maybe_widget_id === $widget_id ) {
57	return (string) $sidebar_id;
58	}
59	}
60	}
61
62	return null;
63	}
64	}
65
66	if ( ! function_exists( 'wp_parse_widget_id' ) ) {
67	/**
68	* Converts a widget ID into its id_base and number components.
69	*
70	* Can be removed when minimum WordPress version is 5.8.
71	*
72	* @since 10.2.0
73	*
74	* @param string $id Widget ID.
75	* @return array Array containing a widget's id_base and number components.
76	*/
77	function wp_parse_widget_id( $id ) {
78	$parsed = array();
79
80	if ( preg_match( '/^(.+)-(\d+)$/', $id, $matches ) ) {
81	$parsed['id_base'] = $matches[1];
82	$parsed['number'] = (int) $matches[2];
83	} else {
84	// Likely an old single widget.
85	$parsed['id_base'] = $id;
86	}
87
88	return $parsed;
89	}
90	}
91
92	if ( ! function_exists( 'wp_render_widget' ) ) {
93	/**
94	* Calls the render callback of a widget and returns the output.
95	*
96	* Can be removed when minimum WordPress version is 5.8.
97	*
98	* @since 10.2.0
99	*
100	* @param string $widget_id Widget ID.
101	* @param string $sidebar_id Sidebar ID.
102	* @return string
103	*/
104	function wp_render_widget( $widget_id, $sidebar_id ) {
105	global $wp_registered_widgets, $wp_registered_sidebars;
106
107	if ( ! isset( $wp_registered_widgets[ $widget_id ] ) ) {
108	return '';
109	}
110
111	if ( isset( $wp_registered_sidebars[ $sidebar_id ] ) ) {
112	$sidebar = $wp_registered_sidebars[ $sidebar_id ];
113	} elseif ( 'wp_inactive_widgets' === $sidebar_id ) {
114	$sidebar = array();
115	} else {
116	return '';
117	}
118
119	$params = array_merge(
120	array(
121	array_merge(
122	$sidebar,
123	array(
124	'widget_id' => $widget_id,
125	'widget_name' => $wp_registered_widgets[ $widget_id ]['name'],
126	)
127	),
128	),
129	(array) $wp_registered_widgets[ $widget_id ]['params']
130	);
131
132	// Substitute HTML `id` and `class` attributes into `before_widget`.
133	$classname_ = '';
134	foreach ( (array) $wp_registered_widgets[ $widget_id ]['classname'] as $cn ) {
135	if ( is_string( $cn ) ) {
136	$classname_ .= '_' . $cn;
137	} elseif ( is_object( $cn ) ) {
138	$classname_ .= '_' . get_class( $cn );
139	}
140	}
141	$classname_ = ltrim( $classname_, '_' );
142	$params[0]['before_widget'] = sprintf( $params[0]['before_widget'], $widget_id, $classname_ );
143
144	/** This filter is documented in wp-includes/widgets.php */
145	$params = apply_filters( 'dynamic_sidebar_params', $params );
146
147	$callback = $wp_registered_widgets[ $widget_id ]['callback'];
148
149	ob_start();
150
151	/** This filter is documented in wp-includes/widgets.php */
152	do_action( 'dynamic_sidebar', $wp_registered_widgets[ $widget_id ] );
153
154	if ( is_callable( $callback ) ) {
155	call_user_func_array( $callback, $params );
156	}
157
158	return ob_get_clean();
159	}
160	}
161
162	if ( ! function_exists( 'wp_render_widget_control' ) ) {
163	/**
164	* Calls the control callback of a widget and returns the output.
165	*
166	* Can be removed when minimum WordPress version is 5.8.
167	*
168	* @since 10.2.0
169	*
170	* @param string $id Widget ID.
171	* @return string\|null
172	*/
173	function wp_render_widget_control( $id ) {
174	global $wp_registered_widget_controls;
175
176	if ( ! isset( $wp_registered_widget_controls[ $id ]['callback'] ) ) {
177	return null;
178	}
179
180	$callback = $wp_registered_widget_controls[ $id ]['callback'];
181	$params = $wp_registered_widget_controls[ $id ]['params'];
182
183	ob_start();
184
185	if ( is_callable( $callback ) ) {
186	call_user_func_array( $callback, $params );
187	}
188
189	return ob_get_clean();
190	}
191	}
192
193	if ( ! function_exists( 'gutenberg_get_widget_instance' ) ) {
194	/**
195	* Returns the instance settings of the given widget. Must be a widget that
196	* is registered using WP_Widget.
197	*
198	* Belongs in WP_Widget when merged to Core.
199	*
200	* Can be removed when minimum WordPress version is 5.8.
201	*
202	* @since 10.2.0
203	*
204	* @param string $id Widget ID.
205	* @return array\|null
206	*/
207	function gutenberg_get_widget_instance( $id ) {
208	$parsed_id = wp_parse_widget_id( $id );
209	$widget_object = gutenberg_get_widget_object( $parsed_id['id_base'] );
210
211	if ( ! isset( $parsed_id['number'] ) \|\| ! $widget_object ) {
212	return null;
213	}
214
215	$all_instances = $widget_object->get_settings();
216	return $all_instances[ $parsed_id['number'] ];
217	}
218	}
219
220	if ( ! function_exists( 'gutenberg_get_widget_key' ) ) {
221	/**
222	* Returns the registered key for the given widget type.
223	*
224	* Belongs in WP_Widget_Factory when merged to Core.
225	*
226	* Can be removed when minimum WordPress version is 5.8.
227	*
228	* @since 10.3.0
229	*
230	* @param string $id_base Widget type ID.
231	* @return string
232	*/
233	function gutenberg_get_widget_key( $id_base ) {
234	global $wp_widget_factory;
235
236	foreach ( $wp_widget_factory->widgets as $key => $widget_object ) {
237	if ( $widget_object->id_base === $id_base ) {
238	return $key;
239	}
240	}
241
242	return '';
243	}
244	}
245
246	if ( ! function_exists( 'gutenberg_get_widget_object' ) ) {
247	/**
248	* Returns the registered WP_Widget object for the given widget type.
249	*
250	* Belongs in WP_Widget_Factory when merged to Core.
251	*
252	* Can be removed when minimum WordPress version is 5.8.
253	*
254	* @since 10.2.0
255	*
256	* @param string $id_base Widget type ID.
257	* @return WP_Widget\|null
258	*/
259	function gutenberg_get_widget_object( $id_base ) {
260	global $wp_widget_factory;
261
262	$key = gutenberg_get_widget_key( $id_base );
263	if ( ! $key ) {
264	return null;
265	}
266
267	return $wp_widget_factory->widgets[ $key ];
268	}
269	}
270