1<?php
2/**
3 * Widget API: WP_Widget base class
4 *
5 * @package WordPress
6 * @subpackage Widgets
7 * @since 4.4.0
8 */
9
10/**
11 * Core base class extended to register widgets.
12 *
13 * This class must be extended for each widget, and WP_Widget::widget() must be overridden.
14 *
15 * If adding widget options, WP_Widget::update() and WP_Widget::form() should also be overridden.
16 *
17 * @since 2.8.0
18 * @since 4.4.0 Moved to its own file from wp-includes/widgets.php
19 */
20#[AllowDynamicProperties]
21class WP_Widget {
22
23 /**
24 * Root ID for all widgets of this type.
25 *
26 * @since 2.8.0
27 * @var mixed|string
28 */
29 public $id_base;
30
31 /**
32 * Name for this widget type.
33 *
34 * @since 2.8.0
35 * @var string
36 */
37 public $name;
38
39 /**
40 * Option name for this widget type.
41 *
42 * @since 2.8.0
43 * @var string
44 */
45 public $option_name;
46
47 /**
48 * Alt option name for this widget type.
49 *
50 * @since 2.8.0
51 * @var string
52 */
53 public $alt_option_name;
54
55 /**
56 * Option array passed to wp_register_sidebar_widget().
57 *
58 * @since 2.8.0
59 * @var array
60 */
61 public $widget_options;
62
63 /**
64 * Option array passed to wp_register_widget_control().
65 *
66 * @since 2.8.0
67 * @var array
68 */
69 public $control_options;
70
71 /**
72 * Unique ID number of the current instance.
73 *
74 * @since 2.8.0
75 * @var bool|int
76 */
77 public $number = false;
78
79 /**
80 * Unique ID string of the current instance (id_base-number).
81 *
82 * @since 2.8.0
83 * @var bool|string
84 */
85 public $id = false;
86
87 /**
88 * Whether the widget data has been updated.
89 *
90 * Set to true when the data is updated after a POST submit - ensures it does
91 * not happen twice.
92 *
93 * @since 2.8.0
94 * @var bool
95 */
96 public $updated = false;
97
98 //
99 // Member functions that must be overridden by subclasses.
100 //
101
102 /**
103 * Echoes the widget content.
104 *
105 * Subclasses should override this function to generate their widget code.
106 *
107 * @since 2.8.0
108 *
109 * @param array $args Display arguments including 'before_title', 'after_title',
110 * 'before_widget', and 'after_widget'.
111 * @param array $instance The settings for the particular instance of the widget.
112 */
113 public function widget( $args, $instance ) {
114 die( 'function WP_Widget::widget() must be overridden in a subclass.' );
115 }
116
117 /**
118 * Updates a particular instance of a widget.
119 *
120 * This function should check that `$new_instance` is set correctly. The newly-calculated
121 * value of `$instance` should be returned. If false is returned, the instance won't be
122 * saved/updated.
123 *
124 * @since 2.8.0
125 *
126 * @param array $new_instance New settings for this instance as input by the user via
127 * WP_Widget::form().
128 * @param array $old_instance Old settings for this instance.
129 * @return array Settings to save or bool false to cancel saving.
130 */
131 public function update( $new_instance, $old_instance ) {
132 return $new_instance;
133 }
134
135 /**
136 * Outputs the settings update form.
137 *
138 * @since 2.8.0
139 *
140 * @param array $instance The settings for the particular instance of the widget.
141 * @return string|void Default return is 'noform'.
142 */
143 public function form( $instance ) {
144 echo '<p class="no-options-widget">' . __( 'There are no options for this widget.' ) . '</p>';
145 return 'noform';
146 }
147
148 // Functions you'll need to call.
149
150 /**
151 * PHP5 constructor.
152 *
153 * @since 2.8.0
154 *
155 * @param string $id_base Base ID for the widget, lowercase and unique. If left empty,
156 * a portion of the widget's PHP class name will be used. Has to be unique.
157 * @param string $name Name for the widget displayed on the configuration page.
158 * @param array $widget_options Optional. Widget options. See wp_register_sidebar_widget() for
159 * information on accepted arguments. Default empty array.
160 * @param array $control_options Optional. Widget control options. See wp_register_widget_control() for
161 * information on accepted arguments. Default empty array.
162 */
163 public function __construct( $id_base, $name, $widget_options = array(), $control_options = array() ) {
164 if ( ! empty( $id_base ) ) {
165 $id_base = strtolower( $id_base );
166 } else {
167 $id_base = preg_replace( '/(wp_)?widget_/', '', strtolower( get_class( $this ) ) );
168 }
169
170 $this->id_base = $id_base;
171 $this->name = $name;
172 $this->option_name = 'widget_' . $this->id_base;
173 $this->widget_options = wp_parse_args(
174 $widget_options,
175 array(
176 'classname' => str_replace( '\\', '_', $this->option_name ),
177 'customize_selective_refresh' => false,
178 )
179 );
180 $this->control_options = wp_parse_args( $control_options, array( 'id_base' => $this->id_base ) );
181 }
182
183 /**
184 * PHP4 constructor.
185 *
186 * @since 2.8.0
187 * @deprecated 4.3.0 Use __construct() instead.
188 *
189 * @see WP_Widget::__construct()
190 *
191 * @param string $id_base Base ID for the widget, lowercase and unique. If left empty,
192 * a portion of the widget's PHP class name will be used. Has to be unique.
193 * @param string $name Name for the widget displayed on the configuration page.
194 * @param array $widget_options Optional. Widget options. See wp_register_sidebar_widget() for
195 * information on accepted arguments. Default empty array.
196 * @param array $control_options Optional. Widget control options. See wp_register_widget_control() for
197 * information on accepted arguments. Default empty array.
198 */
199 public function WP_Widget( $id_base, $name, $widget_options = array(), $control_options = array() ) {
200 _deprecated_constructor( 'WP_Widget', '4.3.0', get_class( $this ) );
201 WP_Widget::__construct( $id_base, $name, $widget_options, $control_options );
202 }
203
204 /**
205 * Constructs name attributes for use in form() fields
206 *
207 * This function should be used in form() methods to create name attributes for fields
208 * to be saved by update()
209 *
210 * @since 2.8.0
211 * @since 4.4.0 Array format field names are now accepted.
212 *
213 * @param string $field_name Field name.
214 * @return string Name attribute for `$field_name`.
215 */
216 public function get_field_name( $field_name ) {
217 $pos = strpos( $field_name, '[' );
218
219 if ( false !== $pos ) {
220 // Replace the first occurrence of '[' with ']['.
221 $field_name = '[' . substr_replace( $field_name, '][', $pos, strlen( '[' ) );
222 } else {
223 $field_name = '[' . $field_name . ']';
224 }
225
226 return 'widget-' . $this->id_base . '[' . $this->number . ']' . $field_name;
227 }
228
229 /**
230 * Constructs id attributes for use in WP_Widget::form() fields.
231 *
232 * This function should be used in form() methods to create id attributes
233 * for fields to be saved by WP_Widget::update().
234 *
235 * @since 2.8.0
236 * @since 4.4.0 Array format field IDs are now accepted.
237 *
238 * @param string $field_name Field name.
239 * @return string ID attribute for `$field_name`.
240 */
241 public function get_field_id( $field_name ) {
242 $field_name = str_replace( array( '[]', '[', ']' ), array( '', '-', '' ), $field_name );
243 $field_name = trim( $field_name, '-' );
244
245 return 'widget-' . $this->id_base . '-' . $this->number . '-' . $field_name;
246 }
247
248 /**
249 * Register all widget instances of this widget class.
250 *
251 * @since 2.8.0
252 */
253 public function _register() {
254 $settings = $this->get_settings();
255 $empty = true;
256
257 // When $settings is an array-like object, get an intrinsic array for use with array_keys().
258 if ( $settings instanceof ArrayObject || $settings instanceof ArrayIterator ) {
259 $settings = $settings->getArrayCopy();
260 }
261
262 if ( is_array( $settings ) ) {
263 foreach ( array_keys( $settings ) as $number ) {
264 if ( is_numeric( $number ) ) {
265 $this->_set( $number );
266 $this->_register_one( $number );
267 $empty = false;
268 }
269 }
270 }
271
272 if ( $empty ) {
273 // If there are none, we register the widget's existence with a generic template.
274 $this->_set( 1 );
275 $this->_register_one();
276 }
277 }
278
279 /**
280 * Sets the internal order number for the widget instance.
281 *
282 * @since 2.8.0
283 *
284 * @param int $number The unique order number of this widget instance compared to other
285 * instances of the same class.
286 */
287 public function _set( $number ) {
288 $this->number = $number;
289 $this->id = $this->id_base . '-' . $number;
290 }
291
292 /**
293 * Retrieves the widget display callback.
294 *
295 * @since 2.8.0
296 *
297 * @return callable Display callback.
298 */
299 public function _get_display_callback() {
300 return array( $this, 'display_callback' );
301 }
302
303 /**
304 * Retrieves the widget update callback.
305 *
306 * @since 2.8.0
307 *
308 * @return callable Update callback.
309 */
310 public function _get_update_callback() {
311 return array( $this, 'update_callback' );
312 }
313
314 /**
315 * Retrieves the form callback.
316 *
317 * @since 2.8.0
318 *
319 * @return callable Form callback.
320 */
321 public function _get_form_callback() {
322 return array( $this, 'form_callback' );
323 }
324
325 /**
326 * Determines whether the current request is inside the Customizer preview.
327 *
328 * If true -- the current request is inside the Customizer preview, then
329 * the object cache gets suspended and widgets should check this to decide
330 * whether they should store anything persistently to the object cache,
331 * to transients, or anywhere else.
332 *
333 * @since 3.9.0
334 *
335 * @global WP_Customize_Manager $wp_customize
336 *
337 * @return bool True if within the Customizer preview, false if not.
338 */
339 public function is_preview() {
340 global $wp_customize;
341 return ( isset( $wp_customize ) && $wp_customize->is_preview() );
342 }
343
344 /**
345 * Generates the actual widget content (Do NOT override).
346 *
347 * Finds the instance and calls WP_Widget::widget().
348 *
349 * @since 2.8.0
350 *
351 * @param array $args Display arguments. See WP_Widget::widget() for information
352 * on accepted arguments.
353 * @param int|array $widget_args {
354 * Optional. Internal order number of the widget instance, or array of multi-widget arguments.
355 * Default 1.
356 *
357 * @type int $number Number increment used for multiples of the same widget.
358 * }
359 */
360 public function display_callback( $args, $widget_args = 1 ) {
361 if ( is_numeric( $widget_args ) ) {
362 $widget_args = array( 'number' => $widget_args );
363 }
364
365 $widget_args = wp_parse_args( $widget_args, array( 'number' => -1 ) );
366 $this->_set( $widget_args['number'] );
367 $instances = $this->get_settings();
368
369 if ( isset( $instances[ $this->number ] ) ) {
370 $instance = $instances[ $this->number ];
371
372 /**
373 * Filters the settings for a particular widget instance.
374 *
375 * Returning false will effectively short-circuit display of the widget.
376 *
377 * @since 2.8.0
378 *
379 * @param array $instance The current widget instance's settings.
380 * @param WP_Widget $widget The current widget instance.
381 * @param array $args An array of default widget arguments.
382 */
383 $instance = apply_filters( 'widget_display_callback', $instance, $this, $args );
384
385 if ( false === $instance ) {
386 return;
387 }
388
389 $was_cache_addition_suspended = wp_suspend_cache_addition();
390 if ( $this->is_preview() && ! $was_cache_addition_suspended ) {
391 wp_suspend_cache_addition( true );
392 }
393
394 $this->widget( $args, $instance );
395
396 if ( $this->is_preview() ) {
397 wp_suspend_cache_addition( $was_cache_addition_suspended );
398 }
399 }
400 }
401
402 /**
403 * Handles changed settings (Do NOT override).
404 *
405 * @since 2.8.0
406 *
407 * @global array $wp_registered_widgets
408 *
409 * @param int $deprecated Not used.
410 */
411 public function update_callback( $deprecated = 1 ) {
412 global $wp_registered_widgets;
413
414 $all_instances = $this->get_settings();
415
416 // We need to update the data.
417 if ( $this->updated ) {
418 return;
419 }
420
421 if ( isset( $_POST['delete_widget'] ) && $_POST['delete_widget'] ) {
422 // Delete the settings for this instance of the widget.
423 if ( isset( $_POST['the-widget-id'] ) ) {
424 $del_id = $_POST['the-widget-id'];
425 } else {
426 return;
427 }
428
429 if ( isset( $wp_registered_widgets[ $del_id ]['params'][0]['number'] ) ) {
430 $number = $wp_registered_widgets[ $del_id ]['params'][0]['number'];
431
432 if ( $this->id_base . '-' . $number === $del_id ) {
433 unset( $all_instances[ $number ] );
434 }
435 }
436 } else {
437 if ( isset( $_POST[ 'widget-' . $this->id_base ] ) && is_array( $_POST[ 'widget-' . $this->id_base ] ) ) {
438 $settings = $_POST[ 'widget-' . $this->id_base ];
439 } elseif ( isset( $_POST['id_base'] ) && $_POST['id_base'] === $this->id_base ) {
440 $num = $_POST['multi_number'] ? (int) $_POST['multi_number'] : (int) $_POST['widget_number'];
441 $settings = array( $num => array() );
442 } else {
443 return;
444 }
445
446 foreach ( $settings as $number => $new_instance ) {
447 $new_instance = stripslashes_deep( $new_instance );
448 $this->_set( $number );
449
450 $old_instance = isset( $all_instances[ $number ] ) ? $all_instances[ $number ] : array();
451
452 $was_cache_addition_suspended = wp_suspend_cache_addition();
453 if ( $this->is_preview() && ! $was_cache_addition_suspended ) {
454 wp_suspend_cache_addition( true );
455 }
456
457 $instance = $this->update( $new_instance, $old_instance );
458
459 if ( $this->is_preview() ) {
460 wp_suspend_cache_addition( $was_cache_addition_suspended );
461 }
462
463 /**
464 * Filters a widget's settings before saving.
465 *
466 * Returning false will effectively short-circuit the widget's ability
467 * to update settings.
468 *
469 * @since 2.8.0
470 *
471 * @param array $instance The current widget instance's settings.
472 * @param array $new_instance Array of new widget settings.
473 * @param array $old_instance Array of old widget settings.
474 * @param WP_Widget $widget The current widget instance.
475 */
476 $instance = apply_filters( 'widget_update_callback', $instance, $new_instance, $old_instance, $this );
477
478 if ( false !== $instance ) {
479 $all_instances[ $number ] = $instance;
480 }
481
482 break; // Run only once.
483 }
484 }
485
486 $this->save_settings( $all_instances );
487 $this->updated = true;
488 }
489
490 /**
491 * Generates the widget control form (Do NOT override).
492 *
493 * @since 2.8.0
494 *
495 * @param int|array $widget_args {
496 * Optional. Internal order number of the widget instance, or array of multi-widget arguments.
497 * Default 1.
498 *
499 * @type int $number Number increment used for multiples of the same widget.
500 * }
501 * @return string|null
502 */
503 public function form_callback( $widget_args = 1 ) {
504 if ( is_numeric( $widget_args ) ) {
505 $widget_args = array( 'number' => $widget_args );
506 }
507
508 $widget_args = wp_parse_args( $widget_args, array( 'number' => -1 ) );
509 $all_instances = $this->get_settings();
510
511 if ( -1 === $widget_args['number'] ) {
512 // We echo out a form where 'number' can be set later.
513 $this->_set( '__i__' );
514 $instance = array();
515 } else {
516 $this->_set( $widget_args['number'] );
517 $instance = $all_instances[ $widget_args['number'] ];
518 }
519
520 /**
521 * Filters the widget instance's settings before displaying the control form.
522 *
523 * Returning false effectively short-circuits display of the control form.
524 *
525 * @since 2.8.0
526 *
527 * @param array $instance The current widget instance's settings.
528 * @param WP_Widget $widget The current widget instance.
529 */
530 $instance = apply_filters( 'widget_form_callback', $instance, $this );
531
532 $return = null;
533
534 if ( false !== $instance ) {
535 $return = $this->form( $instance );
536
537 /**
538 * Fires at the end of the widget control form.
539 *
540 * Use this hook to add extra fields to the widget form. The hook
541 * is only fired if the value passed to the 'widget_form_callback'
542 * hook is not false.
543 *
544 * Note: If the widget has no form, the text echoed from the default
545 * form method can be hidden using CSS.
546 *
547 * @since 2.8.0
548 *
549 * @param WP_Widget $widget The widget instance (passed by reference).
550 * @param null $return Return null if new fields are added.
551 * @param array $instance An array of the widget's settings.
552 */
553 do_action_ref_array( 'in_widget_form', array( &$this, &$return, $instance ) );
554 }
555
556 return $return;
557 }
558
559 /**
560 * Registers an instance of the widget class.
561 *
562 * @since 2.8.0
563 *
564 * @param int $number Optional. The unique order number of this widget instance
565 * compared to other instances of the same class. Default -1.
566 */
567 public function _register_one( $number = -1 ) {
568 wp_register_sidebar_widget(
569 $this->id,
570 $this->name,
571 $this->_get_display_callback(),
572 $this->widget_options,
573 array( 'number' => $number )
574 );
575
576 _register_widget_update_callback(
577 $this->id_base,
578 $this->_get_update_callback(),
579 $this->control_options,
580 array( 'number' => -1 )
581 );
582
583 _register_widget_form_callback(
584 $this->id,
585 $this->name,
586 $this->_get_form_callback(),
587 $this->control_options,
588 array( 'number' => $number )
589 );
590 }
591
592 /**
593 * Saves the settings for all instances of the widget class.
594 *
595 * @since 2.8.0
596 *
597 * @param array $settings Multi-dimensional array of widget instance settings.
598 */
599 public function save_settings( $settings ) {
600 $settings['_multiwidget'] = 1;
601 update_option( $this->option_name, $settings );
602 }
603
604 /**
605 * Retrieves the settings for all instances of the widget class.
606 *
607 * @since 2.8.0
608 *
609 * @return array Multi-dimensional array of widget instance settings.
610 */
611 public function get_settings() {
612
613 $settings = get_option( $this->option_name );
614
615 if ( false === $settings ) {
616 $settings = array();
617 if ( isset( $this->alt_option_name ) ) {
618 // Get settings from alternative (legacy) option.
619 $settings = get_option( $this->alt_option_name, array() );
620
621 // Delete the alternative (legacy) option as the new option will be created using `$this->option_name`.
622 delete_option( $this->alt_option_name );
623 }
624 // Save an option so it can be autoloaded next time.
625 $this->save_settings( $settings );
626 }
627
628 if ( ! is_array( $settings ) && ! ( $settings instanceof ArrayObject || $settings instanceof ArrayIterator ) ) {
629 $settings = array();
630 }
631
632 if ( ! empty( $settings ) && ! isset( $settings['_multiwidget'] ) ) {
633 // Old format, convert if single widget.
634 $settings = wp_convert_widget_settings( $this->id_base, $this->option_name, $settings );
635 }
636
637 unset( $settings['_multiwidget'], $settings['__i__'] );
638
639 return $settings;
640 }
641}
642