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