WordPress 4.3
[autoinstalls/wordpress.git] / wp-includes / widgets.php
1 <?php
2 /**
3  * API for creating dynamic sidebar without hardcoding functionality into
4  * themes. Includes both internal WordPress routines and theme use routines.
5  *
6  * This functionality was found in a plugin before WordPress 2.2 release which
7  * included it in the core from that point on.
8  *
9  * @link https://codex.wordpress.org/Plugins/WordPress_Widgets WordPress Widgets
10  * @link https://codex.wordpress.org/Plugins/WordPress_Widgets_Api Widgets API
11  *
12  * @package WordPress
13  * @subpackage Widgets
14  */
15
16 /**
17  * This class must be extended for each widget and WP_Widget::widget(), WP_Widget::update()
18  * and WP_Widget::form() need to be over-ridden.
19  *
20  * @package WordPress
21  * @subpackage Widgets
22  * @since 2.8.0
23  */
24 class WP_Widget {
25
26         /**
27          * Root ID for all widgets of this type.
28          *
29          * @since 2.8.0
30          * @access public
31          * @var mixed|string
32          */
33         public $id_base;
34
35         /**
36          * Name for this widget type.
37          *
38          * @since 2.8.0
39          * @access public
40          * @var string
41          */
42         public $name;
43
44         /**
45          * Option array passed to {@see wp_register_sidebar_widget()}.
46          *
47          * @since 2.8.0
48          * @access public
49          * @var array
50          */
51         public $widget_options;
52
53         /**
54          * Option array passed to {@see wp_register_widget_control()}.
55          *
56          * @since 2.8.0
57          * @access public
58          * @var array
59          */
60         public $control_options;
61
62         /**
63          * Unique ID number of the current instance.
64          *
65          * @since 2.8.0
66          * @access public
67          * @var bool|int
68          */
69         public $number = false;
70
71         /**
72          * Unique ID string of the current instance (id_base-number).
73          *
74          * @since 2.8.0
75          * @access public
76          * @var bool|string
77          */
78         public $id = false;
79
80         /**
81          * Whether the widget data has been updated.
82          *
83          * Set to true when the data is updated after a POST submit - ensures it does
84          * not happen twice.
85          *
86          * @since 2.8.0
87          * @access public
88          * @var bool
89          */
90         public $updated = false;
91
92         // Member functions that you must over-ride.
93
94         /**
95          * Echo the widget content.
96          *
97          * Subclasses should over-ride this function to generate their widget code.
98          *
99          * @since 2.8.0
100          * @access public
101          *
102          * @param array $args     Display arguments including before_title, after_title,
103          *                        before_widget, and after_widget.
104          * @param array $instance The settings for the particular instance of the widget.
105          */
106         public function widget( $args, $instance ) {
107                 die('function WP_Widget::widget() must be over-ridden in a sub-class.');
108         }
109
110         /**
111          * Update a particular instance.
112          *
113          * This function should check that $new_instance is set correctly. The newly-calculated
114          * value of `$instance` should be returned. If false is returned, the instance won't be
115          * saved/updated.
116          *
117          * @since 2.8.0
118          * @access public
119          *
120          * @param array $new_instance New settings for this instance as input by the user via
121          *                            {@see WP_Widget::form()}.
122          * @param array $old_instance Old settings for this instance.
123          * @return array Settings to save or bool false to cancel saving.
124          */
125         public function update( $new_instance, $old_instance ) {
126                 return $new_instance;
127         }
128
129         /**
130          * Output the settings update form.
131          *
132          * @since 2.8.0
133          * @access public
134          *
135          * @param array $instance Current settings.
136          * @return string Default return is 'noform'.
137          */
138         public function form($instance) {
139                 echo '<p class="no-options-widget">' . __('There are no options for this widget.') . '</p>';
140                 return 'noform';
141         }
142
143         // Functions you'll need to call.
144
145         /**
146          * PHP5 constructor.
147          *
148          * @since 2.8.0
149          * @access public
150          *
151          * @param string $id_base         Optional Base ID for the widget, lowercase and unique. If left empty,
152          *                                a portion of the widget's class name will be used Has to be unique.
153          * @param string $name            Name for the widget displayed on the configuration page.
154          * @param array  $widget_options  Optional. Widget options. See {@see wp_register_sidebar_widget()} for
155          *                                information on accepted arguments. Default empty array.
156          * @param array  $control_options Optional. Widget control options. See {@see wp_register_widget_control()}
157          *                                for information on accepted arguments. Default empty array.
158          */
159         public function __construct( $id_base, $name, $widget_options = array(), $control_options = array() ) {
160                 $this->id_base = empty($id_base) ? preg_replace( '/(wp_)?widget_/', '', strtolower(get_class($this)) ) : strtolower($id_base);
161                 $this->name = $name;
162                 $this->option_name = 'widget_' . $this->id_base;
163                 $this->widget_options = wp_parse_args( $widget_options, array('classname' => $this->option_name) );
164                 $this->control_options = wp_parse_args( $control_options, array('id_base' => $this->id_base) );
165         }
166
167         /**
168          * PHP4 constructor
169          *
170          * @param string $id_base
171          * @param string $name
172          * @param array  $widget_options
173          * @param array  $control_options
174          */
175         public function WP_Widget( $id_base, $name, $widget_options = array(), $control_options = array() ) {
176                 _deprecated_constructor( 'WP_Widget', '4.3.0' );
177                 WP_Widget::__construct( $id_base, $name, $widget_options, $control_options );
178         }
179
180         /**
181          * Constructs name attributes for use in form() fields
182          *
183          * This function should be used in form() methods to create name attributes for fields to be saved by update()
184          *
185          * @param string $field_name Field name
186          * @return string Name attribute for $field_name
187          */
188         public function get_field_name($field_name) {
189                 return 'widget-' . $this->id_base . '[' . $this->number . '][' . $field_name . ']';
190         }
191
192         /**
193          * Constructs id attributes for use in {@see WP_Widget::form()} fields.
194          *
195          * This function should be used in form() methods to create id attributes
196          * for fields to be saved by {@see WP_Widget::update()}.
197          *
198          * @since 2.8.0
199          * @access public
200          *
201          * @param string $field_name Field name.
202          * @return string ID attribute for `$field_name`.
203          */
204         public function get_field_id( $field_name ) {
205                 return 'widget-' . $this->id_base . '-' . $this->number . '-' . $field_name;
206         }
207
208         /**
209          * Register all widget instances of this widget class.
210          *
211          * @since 2.8.0
212          * @access private
213          */
214         public function _register() {
215                 $settings = $this->get_settings();
216                 $empty = true;
217
218                 // When $settings is an array-like object, get an intrinsic array for use with array_keys().
219                 if ( $settings instanceof ArrayObject || $settings instanceof ArrayIterator ) {
220                         $settings = $settings->getArrayCopy();
221                 }
222
223                 if ( is_array( $settings ) ) {
224                         foreach ( array_keys( $settings ) as $number ) {
225                                 if ( is_numeric( $number ) ) {
226                                         $this->_set( $number );
227                                         $this->_register_one( $number );
228                                         $empty = false;
229                                 }
230                         }
231                 }
232
233                 if ( $empty ) {
234                         // If there are none, we register the widget's existence with a generic template.
235                         $this->_set( 1 );
236                         $this->_register_one();
237                 }
238         }
239
240         /**
241          * Set the internal order number for the widget instance.
242          *
243          * @since 2.8.0
244          * @access private
245          *
246          * @param int $number The unique order number of this widget instance compared to other
247          *                    instances of the same class.
248          */
249         public function _set($number) {
250                 $this->number = $number;
251                 $this->id = $this->id_base . '-' . $number;
252         }
253
254         /**
255          * @return callback
256          */
257         public function _get_display_callback() {
258                 return array($this, 'display_callback');
259         }
260         /**
261          * @return callback
262          */
263         public function _get_update_callback() {
264                 return array($this, 'update_callback');
265         }
266         /**
267          * @return callback
268          */
269         public function _get_form_callback() {
270                 return array($this, 'form_callback');
271         }
272
273         /**
274          * Determine whether the current request is inside the Customizer preview.
275          *
276          * If true -- the current request is inside the Customizer preview, then
277          * the object cache gets suspended and widgets should check this to decide
278          * whether they should store anything persistently to the object cache,
279          * to transients, or anywhere else.
280          *
281          * @since 3.9.0
282          * @access public
283          *
284          * @global WP_Customize_Manager $wp_customize
285          *
286          * @return bool True if within the Customizer preview, false if not.
287          */
288         public function is_preview() {
289                 global $wp_customize;
290                 return ( isset( $wp_customize ) && $wp_customize->is_preview() ) ;
291         }
292
293         /**
294          * Generate the actual widget content (Do NOT override).
295          *
296          * Finds the instance and calls {@see WP_Widget::widget()}.
297          *
298          * @since 2.8.0
299          * @access public
300          *
301          * @param array     $args        Display arguments. See {@see WP_Widget::widget()} for information
302          *                               on accepted arguments.
303          * @param int|array $widget_args {
304          *     Optional. Internal order number of the widget instance, or array of multi-widget arguments.
305          *     Default 1.
306          *
307          *     @type int $number Number increment used for multiples of the same widget.
308          * }
309          */
310         public function display_callback( $args, $widget_args = 1 ) {
311                 if ( is_numeric( $widget_args ) ) {
312                         $widget_args = array( 'number' => $widget_args );
313                 }
314
315                 $widget_args = wp_parse_args( $widget_args, array( 'number' => -1 ) );
316                 $this->_set( $widget_args['number'] );
317                 $instances = $this->get_settings();
318
319                 if ( isset( $instances[ $this->number ] ) ) {
320                         $instance = $instances[ $this->number ];
321
322                         /**
323                          * Filter the settings for a particular widget instance.
324                          *
325                          * Returning false will effectively short-circuit display of the widget.
326                          *
327                          * @since 2.8.0
328                          *
329                          * @param array     $instance The current widget instance's settings.
330                          * @param WP_Widget $this     The current widget instance.
331                          * @param array     $args     An array of default widget arguments.
332                          */
333                         $instance = apply_filters( 'widget_display_callback', $instance, $this, $args );
334
335                         if ( false === $instance ) {
336                                 return;
337                         }
338
339                         $was_cache_addition_suspended = wp_suspend_cache_addition();
340                         if ( $this->is_preview() && ! $was_cache_addition_suspended ) {
341                                 wp_suspend_cache_addition( true );
342                         }
343
344                         $this->widget( $args, $instance );
345
346                         if ( $this->is_preview() ) {
347                                 wp_suspend_cache_addition( $was_cache_addition_suspended );
348                         }
349                 }
350         }
351
352         /**
353          * Deal with changed settings (Do NOT override).
354          *
355          * @since 2.8.0
356          * @access public
357          *
358          * @global array $wp_registered_widgets
359          *
360          * @param int $deprecated Not used.
361          */
362         public function update_callback( $deprecated = 1 ) {
363                 global $wp_registered_widgets;
364
365                 $all_instances = $this->get_settings();
366
367                 // We need to update the data
368                 if ( $this->updated )
369                         return;
370
371                 if ( isset($_POST['delete_widget']) && $_POST['delete_widget'] ) {
372                         // Delete the settings for this instance of the widget
373                         if ( isset($_POST['the-widget-id']) )
374                                 $del_id = $_POST['the-widget-id'];
375                         else
376                                 return;
377
378                         if ( isset($wp_registered_widgets[$del_id]['params'][0]['number']) ) {
379                                 $number = $wp_registered_widgets[$del_id]['params'][0]['number'];
380
381                                 if ( $this->id_base . '-' . $number == $del_id )
382                                         unset($all_instances[$number]);
383                         }
384                 } else {
385                         if ( isset($_POST['widget-' . $this->id_base]) && is_array($_POST['widget-' . $this->id_base]) ) {
386                                 $settings = $_POST['widget-' . $this->id_base];
387                         } elseif ( isset($_POST['id_base']) && $_POST['id_base'] == $this->id_base ) {
388                                 $num = $_POST['multi_number'] ? (int) $_POST['multi_number'] : (int) $_POST['widget_number'];
389                                 $settings = array( $num => array() );
390                         } else {
391                                 return;
392                         }
393
394                         foreach ( $settings as $number => $new_instance ) {
395                                 $new_instance = stripslashes_deep($new_instance);
396                                 $this->_set($number);
397
398                                 $old_instance = isset($all_instances[$number]) ? $all_instances[$number] : array();
399
400                                 $was_cache_addition_suspended = wp_suspend_cache_addition();
401                                 if ( $this->is_preview() && ! $was_cache_addition_suspended ) {
402                                         wp_suspend_cache_addition( true );
403                                 }
404
405                                 $instance = $this->update( $new_instance, $old_instance );
406
407                                 if ( $this->is_preview() ) {
408                                         wp_suspend_cache_addition( $was_cache_addition_suspended );
409                                 }
410
411                                 /**
412                                  * Filter a widget's settings before saving.
413                                  *
414                                  * Returning false will effectively short-circuit the widget's ability
415                                  * to update settings.
416                                  *
417                                  * @since 2.8.0
418                                  *
419                                  * @param array     $instance     The current widget instance's settings.
420                                  * @param array     $new_instance Array of new widget settings.
421                                  * @param array     $old_instance Array of old widget settings.
422                                  * @param WP_Widget $this         The current widget instance.
423                                  */
424                                 $instance = apply_filters( 'widget_update_callback', $instance, $new_instance, $old_instance, $this );
425                                 if ( false !== $instance ) {
426                                         $all_instances[$number] = $instance;
427                                 }
428
429                                 break; // run only once
430                         }
431                 }
432
433                 $this->save_settings($all_instances);
434                 $this->updated = true;
435         }
436
437         /**
438          * Generate the widget control form (Do NOT override).
439          *
440          * @since 2.8.0
441          * @access public
442          *
443          * @param int|array $widget_args Widget instance number or array of widget arguments.
444          * @return string|null
445          */
446         public function form_callback( $widget_args = 1 ) {
447                 if ( is_numeric($widget_args) )
448                         $widget_args = array( 'number' => $widget_args );
449
450                 $widget_args = wp_parse_args( $widget_args, array( 'number' => -1 ) );
451                 $all_instances = $this->get_settings();
452
453                 if ( -1 == $widget_args['number'] ) {
454                         // We echo out a form where 'number' can be set later
455                         $this->_set('__i__');
456                         $instance = array();
457                 } else {
458                         $this->_set($widget_args['number']);
459                         $instance = $all_instances[ $widget_args['number'] ];
460                 }
461
462                 /**
463                  * Filter the widget instance's settings before displaying the control form.
464                  *
465                  * Returning false effectively short-circuits display of the control form.
466                  *
467                  * @since 2.8.0
468                  *
469                  * @param array     $instance The current widget instance's settings.
470                  * @param WP_Widget $this     The current widget instance.
471                  */
472                 $instance = apply_filters( 'widget_form_callback', $instance, $this );
473
474                 $return = null;
475                 if ( false !== $instance ) {
476                         $return = $this->form($instance);
477
478                         /**
479                          * Fires at the end of the widget control form.
480                          *
481                          * Use this hook to add extra fields to the widget form. The hook
482                          * is only fired if the value passed to the 'widget_form_callback'
483                          * hook is not false.
484                          *
485                          * Note: If the widget has no form, the text echoed from the default
486                          * form method can be hidden using CSS.
487                          *
488                          * @since 2.8.0
489                          *
490                          * @param WP_Widget $this     The widget instance, passed by reference.
491                          * @param null      $return   Return null if new fields are added.
492                          * @param array     $instance An array of the widget's settings.
493                          */
494                         do_action_ref_array( 'in_widget_form', array( &$this, &$return, $instance ) );
495                 }
496                 return $return;
497         }
498
499         /**
500          * Register an instance of the widget class.
501          *
502          * @since 2.8.0
503          * @access private
504          *
505          * @param integer $number Optional. The unique order number of this widget instance
506          *                        compared to other instances of the same class. Default -1.
507          */
508         public function _register_one( $number = -1 ) {
509                 wp_register_sidebar_widget(     $this->id, $this->name, $this->_get_display_callback(), $this->widget_options, array( 'number' => $number ) );
510                 _register_widget_update_callback( $this->id_base, $this->_get_update_callback(), $this->control_options, array( 'number' => -1 ) );
511                 _register_widget_form_callback( $this->id, $this->name, $this->_get_form_callback(), $this->control_options, array( 'number' => $number ) );
512         }
513
514         /**
515          * Save the settings for all instances of the widget class.
516          *
517          * @since 2.8.0
518          * @access public
519          *
520          * @param array $settings Multi-dimensional array of widget instance settings.
521          */
522         public function save_settings( $settings ) {
523                 $settings['_multiwidget'] = 1;
524                 update_option( $this->option_name, $settings );
525         }
526
527         /**
528          * Get the settings for all instances of the widget class.
529          *
530          * @since 2.8.0
531          * @access public
532          *
533          * @return array Multi-dimensional array of widget instance settings.
534          */
535         public function get_settings() {
536
537                 $settings = get_option( $this->option_name );
538
539                 if ( false === $settings && isset( $this->alt_option_name ) ) {
540                         $settings = get_option( $this->alt_option_name );
541                 }
542
543                 if ( ! is_array( $settings ) && ! ( $settings instanceof ArrayObject || $settings instanceof ArrayIterator ) ) {
544                         $settings = array();
545                 }
546
547                 if ( ! empty( $settings ) && ! isset( $settings['_multiwidget'] ) ) {
548                         // Old format, convert if single widget.
549                         $settings = wp_convert_widget_settings( $this->id_base, $this->option_name, $settings );
550                 }
551
552                 unset( $settings['_multiwidget'], $settings['__i__'] );
553                 return $settings;
554         }
555 }
556
557 /**
558  * Singleton that registers and instantiates WP_Widget classes.
559  *
560  * @package WordPress
561  * @subpackage Widgets
562  * @since 2.8.0
563  */
564 class WP_Widget_Factory {
565         public $widgets = array();
566
567         /**
568          * PHP5 constructor.
569          */
570         public function __construct() {
571                 add_action( 'widgets_init', array( $this, '_register_widgets' ), 100 );
572         }
573
574         /**
575          * PHP4 constructor.
576          */
577         public function WP_Widget_Factory() {
578                 _deprecated_constructor( 'WP_Widget_Factory', '4.2.0' );
579                 self::__construct();
580         }
581
582         /**
583          * Register a widget subclass.
584          *
585          * @since 2.8.0
586          * @access public
587          *
588          * @param string $widget_class The name of a {@see WP_Widget} subclass.
589          */
590         public function register( $widget_class ) {
591                 $this->widgets[$widget_class] = new $widget_class();
592         }
593
594         /**
595          * Un-register a widget subclass.
596          *
597          * @since 2.8.0
598          * @access public
599          *
600          * @param string $widget_class The name of a {@see WP_Widget} subclass.
601          */
602         public function unregister( $widget_class ) {
603                 unset( $this->widgets[ $widget_class ] );
604         }
605
606         /**
607          * Utility method for adding widgets to the registered widgets global.
608          *
609          * @since 2.8.0
610          * @access public
611          *
612          * @global array $wp_registered_widgets
613          */
614         public function _register_widgets() {
615                 global $wp_registered_widgets;
616                 $keys = array_keys($this->widgets);
617                 $registered = array_keys($wp_registered_widgets);
618                 $registered = array_map('_get_widget_id_base', $registered);
619
620                 foreach ( $keys as $key ) {
621                         // don't register new widget if old widget with the same id is already registered
622                         if ( in_array($this->widgets[$key]->id_base, $registered, true) ) {
623                                 unset($this->widgets[$key]);
624                                 continue;
625                         }
626
627                         $this->widgets[$key]->_register();
628                 }
629         }
630 }
631
632 /* Global Variables */
633
634 /** @ignore */
635 global $wp_registered_sidebars, $wp_registered_widgets, $wp_registered_widget_controls, $wp_registered_widget_updates;
636
637 /**
638  * Stores the sidebars, since many themes can have more than one.
639  *
640  * @global array $wp_registered_sidebars
641  * @since 2.2.0
642  */
643 $wp_registered_sidebars = array();
644
645 /**
646  * Stores the registered widgets.
647  *
648  * @global array $wp_registered_widgets
649  * @since 2.2.0
650  */
651 $wp_registered_widgets = array();
652
653 /**
654  * Stores the registered widget control (options).
655  *
656  * @global array $wp_registered_widget_controls
657  * @since 2.2.0
658  */
659 $wp_registered_widget_controls = array();
660 /**
661  * @global array $wp_registered_widget_updates
662  */
663 $wp_registered_widget_updates = array();
664
665 /**
666  * Private
667  *
668  * @global array $_wp_sidebars_widgets
669  */
670 $_wp_sidebars_widgets = array();
671
672 /**
673  * Private
674  *
675  * @global array $_wp_deprecated_widgets_callbacks
676  */
677 $GLOBALS['_wp_deprecated_widgets_callbacks'] = array(
678         'wp_widget_pages',
679         'wp_widget_pages_control',
680         'wp_widget_calendar',
681         'wp_widget_calendar_control',
682         'wp_widget_archives',
683         'wp_widget_archives_control',
684         'wp_widget_links',
685         'wp_widget_meta',
686         'wp_widget_meta_control',
687         'wp_widget_search',
688         'wp_widget_recent_entries',
689         'wp_widget_recent_entries_control',
690         'wp_widget_tag_cloud',
691         'wp_widget_tag_cloud_control',
692         'wp_widget_categories',
693         'wp_widget_categories_control',
694         'wp_widget_text',
695         'wp_widget_text_control',
696         'wp_widget_rss',
697         'wp_widget_rss_control',
698         'wp_widget_recent_comments',
699         'wp_widget_recent_comments_control'
700 );
701
702 /* Template tags & API functions */
703
704 /**
705  * Register a widget
706  *
707  * Registers a WP_Widget widget
708  *
709  * @since 2.8.0
710  *
711  * @see WP_Widget
712  *
713  * @global WP_Widget_Factory $wp_widget_factory
714  *
715  * @param string $widget_class The name of a class that extends WP_Widget
716  */
717 function register_widget($widget_class) {
718         global $wp_widget_factory;
719
720         $wp_widget_factory->register($widget_class);
721 }
722
723 /**
724  * Unregister a widget
725  *
726  * Unregisters a WP_Widget widget. Useful for unregistering default widgets.
727  * Run within a function hooked to the widgets_init action.
728  *
729  * @since 2.8.0
730  *
731  * @see WP_Widget
732  *
733  * @global WP_Widget_Factory $wp_widget_factory
734  *
735  * @param string $widget_class The name of a class that extends WP_Widget
736  */
737 function unregister_widget($widget_class) {
738         global $wp_widget_factory;
739
740         $wp_widget_factory->unregister($widget_class);
741 }
742
743 /**
744  * Creates multiple sidebars.
745  *
746  * If you wanted to quickly create multiple sidebars for a theme or internally.
747  * This function will allow you to do so. If you don't pass the 'name' and/or
748  * 'id' in `$args`, then they will be built for you.
749  *
750  * @since 2.2.0
751  *
752  * @see register_sidebar() The second parameter is documented by register_sidebar() and is the same here.
753  *
754  * @global array $wp_registered_sidebars
755  *
756  * @param int          $number Optional. Number of sidebars to create. Default 1.
757  * @param array|string $args {
758  *     Optional. Array or string of arguments for building a sidebar.
759  *
760  *     @type string $id   The base string of the unique identifier for each sidebar. If provided, and multiple
761  *                        sidebars are being defined, the id will have "-2" appended, and so on.
762  *                        Default 'sidebar-' followed by the number the sidebar creation is currently at.
763  *     @type string $name The name or title for the sidebars displayed in the admin dashboard. If registering
764  *                        more than one sidebar, include '%d' in the string as a placeholder for the uniquely
765  *                        assigned number for each sidebar.
766  *                        Default 'Sidebar' for the first sidebar, otherwise 'Sidebar %d'.
767  * }
768  */
769 function register_sidebars( $number = 1, $args = array() ) {
770         global $wp_registered_sidebars;
771         $number = (int) $number;
772
773         if ( is_string($args) )
774                 parse_str($args, $args);
775
776         for ( $i = 1; $i <= $number; $i++ ) {
777                 $_args = $args;
778
779                 if ( $number > 1 )
780                         $_args['name'] = isset($args['name']) ? sprintf($args['name'], $i) : sprintf(__('Sidebar %d'), $i);
781                 else
782                         $_args['name'] = isset($args['name']) ? $args['name'] : __('Sidebar');
783
784                 // Custom specified ID's are suffixed if they exist already.
785                 // Automatically generated sidebar names need to be suffixed regardless starting at -0
786                 if ( isset($args['id']) ) {
787                         $_args['id'] = $args['id'];
788                         $n = 2; // Start at -2 for conflicting custom ID's
789                         while ( isset($wp_registered_sidebars[$_args['id']]) )
790                                 $_args['id'] = $args['id'] . '-' . $n++;
791                 } else {
792                         $n = count($wp_registered_sidebars);
793                         do {
794                                 $_args['id'] = 'sidebar-' . ++$n;
795                         } while ( isset($wp_registered_sidebars[$_args['id']]) );
796                 }
797                 register_sidebar($_args);
798         }
799 }
800
801 /**
802  * Builds the definition for a single sidebar and returns the ID.
803  *
804  * Accepts either a string or an array and then parses that against a set
805  * of default arguments for the new sidebar. WordPress will automatically
806  * generate a sidebar ID and name based on the current number of registered
807  * sidebars if those arguments are not included.
808  *
809  * When allowing for automatic generation of the name and ID parameters, keep
810  * in mind that the incrementor for your sidebar can change over time depending
811  * on what other plugins and themes are installed.
812  *
813  * If theme support for 'widgets' has not yet been added when this function is
814  * called, it will be automatically enabled through the use of add_theme_support()
815  *
816  * @since 2.2.0
817  *
818  * @global array $wp_registered_sidebars Stores the new sidebar in this array by sidebar ID.
819  *
820  * @param array|string $args {
821  *     Optional. Array or string of arguments for the sidebar being registered.
822  *
823  *     @type string $name          The name or title of the sidebar displayed in the Widgets
824  *                                 interface. Default 'Sidebar $instance'.
825  *     @type string $id            The unique identifier by which the sidebar will be called.
826  *                                 Default 'sidebar-$instance'.
827  *     @type string $description   Description of the sidebar, displayed in the Widgets interface.
828  *                                 Default empty string.
829  *     @type string $class         Extra CSS class to assign to the sidebar in the Widgets interface.
830  *                                 Default empty.
831  *     @type string $before_widget HTML content to prepend to each widget's HTML output when
832  *                                 assigned to this sidebar. Default is an opening list item element.
833  *     @type string $after_widget  HTML content to append to each widget's HTML output when
834  *                                 assigned to this sidebar. Default is a closing list item element.
835  *     @type string $before_title  HTML content to prepend to the sidebar title when displayed.
836  *                                 Default is an opening h2 element.
837  *     @type string $after_title   HTML content to append to the sidebar title when displayed.
838  *                                 Default is a closing h2 element.
839  * }
840  * @return string Sidebar ID added to $wp_registered_sidebars global.
841  */
842 function register_sidebar($args = array()) {
843         global $wp_registered_sidebars;
844
845         $i = count($wp_registered_sidebars) + 1;
846
847         $id_is_empty = empty( $args['id'] );
848
849         $defaults = array(
850                 'name' => sprintf(__('Sidebar %d'), $i ),
851                 'id' => "sidebar-$i",
852                 'description' => '',
853                 'class' => '',
854                 'before_widget' => '<li id="%1$s" class="widget %2$s">',
855                 'after_widget' => "</li>\n",
856                 'before_title' => '<h2 class="widgettitle">',
857                 'after_title' => "</h2>\n",
858         );
859
860         $sidebar = wp_parse_args( $args, $defaults );
861
862         if ( $id_is_empty ) {
863                 /* translators: 1: the id argument, 2: sidebar name, 3: recommended id value */
864                 _doing_it_wrong( __FUNCTION__, sprintf( __( 'No %1$s was set in the arguments array for the "%2$s" sidebar. Defaulting to "%3$s". Manually set the %1$s to "%3$s" to silence this notice and keep existing sidebar content.' ), '<code>id</code>', $sidebar['name'], $sidebar['id'] ), '4.2.0' );
865         }
866
867         $wp_registered_sidebars[$sidebar['id']] = $sidebar;
868
869         add_theme_support('widgets');
870
871         /**
872          * Fires once a sidebar has been registered.
873          *
874          * @since 3.0.0
875          *
876          * @param array $sidebar Parsed arguments for the registered sidebar.
877          */
878         do_action( 'register_sidebar', $sidebar );
879
880         return $sidebar['id'];
881 }
882
883 /**
884  * Removes a sidebar from the list.
885  *
886  * @since 2.2.0
887  *
888  * @global array $wp_registered_sidebars Stores the new sidebar in this array by sidebar ID.
889  *
890  * @param string $name The ID of the sidebar when it was added.
891  */
892 function unregister_sidebar( $name ) {
893         global $wp_registered_sidebars;
894
895         unset( $wp_registered_sidebars[ $name ] );
896 }
897
898 /**
899  * Register an instance of a widget.
900  *
901  * The default widget option is 'classname' that can be overridden.
902  *
903  * The function can also be used to un-register widgets when `$output_callback`
904  * parameter is an empty string.
905  *
906  * @since 2.2.0
907  *
908  * @global array $wp_registered_widgets       Uses stored registered widgets.
909  * @global array $wp_register_widget_defaults Retrieves widget defaults.
910  * @global array $wp_registered_widget_updates
911  * @global array $_wp_deprecated_widgets_callbacks
912  *
913  * @param int|string $id              Widget ID.
914  * @param string     $name            Widget display title.
915  * @param callback   $output_callback Run when widget is called.
916  * @param array      $options {
917  *     Optional. An array of supplementary widget options for the instance.
918  *
919  *     @type string $classname   Class name for the widget's HTML container. Default is a shortened
920  *                               version of the output callback name.
921  *     @type string $description Widget description for display in the widget administration
922  *                               panel and/or theme.
923  * }
924  */
925 function wp_register_sidebar_widget( $id, $name, $output_callback, $options = array() ) {
926         global $wp_registered_widgets, $wp_registered_widget_controls, $wp_registered_widget_updates, $_wp_deprecated_widgets_callbacks;
927
928         $id = strtolower($id);
929
930         if ( empty($output_callback) ) {
931                 unset($wp_registered_widgets[$id]);
932                 return;
933         }
934
935         $id_base = _get_widget_id_base($id);
936         if ( in_array($output_callback, $_wp_deprecated_widgets_callbacks, true) && !is_callable($output_callback) ) {
937                 unset( $wp_registered_widget_controls[ $id ] );
938                 unset( $wp_registered_widget_updates[ $id_base ] );
939                 return;
940         }
941
942         $defaults = array('classname' => $output_callback);
943         $options = wp_parse_args($options, $defaults);
944         $widget = array(
945                 'name' => $name,
946                 'id' => $id,
947                 'callback' => $output_callback,
948                 'params' => array_slice(func_get_args(), 4)
949         );
950         $widget = array_merge($widget, $options);
951
952         if ( is_callable($output_callback) && ( !isset($wp_registered_widgets[$id]) || did_action( 'widgets_init' ) ) ) {
953
954                 /**
955                  * Fires once for each registered widget.
956                  *
957                  * @since 3.0.0
958                  *
959                  * @param array $widget An array of default widget arguments.
960                  */
961                 do_action( 'wp_register_sidebar_widget', $widget );
962                 $wp_registered_widgets[$id] = $widget;
963         }
964 }
965
966 /**
967  * Retrieve description for widget.
968  *
969  * When registering widgets, the options can also include 'description' that
970  * describes the widget for display on the widget administration panel or
971  * in the theme.
972  *
973  * @since 2.5.0
974  *
975  * @global array $wp_registered_widgets
976  *
977  * @param int|string $id Widget ID.
978  * @return string|void Widget description, if available.
979  */
980 function wp_widget_description( $id ) {
981         if ( !is_scalar($id) )
982                 return;
983
984         global $wp_registered_widgets;
985
986         if ( isset($wp_registered_widgets[$id]['description']) )
987                 return esc_html( $wp_registered_widgets[$id]['description'] );
988 }
989
990 /**
991  * Retrieve description for a sidebar.
992  *
993  * When registering sidebars a 'description' parameter can be included that
994  * describes the sidebar for display on the widget administration panel.
995  *
996  * @since 2.9.0
997  *
998  * @global array $wp_registered_sidebars
999  *
1000  * @param string $id sidebar ID.
1001  * @return string|void Sidebar description, if available.
1002  */
1003 function wp_sidebar_description( $id ) {
1004         if ( !is_scalar($id) )
1005                 return;
1006
1007         global $wp_registered_sidebars;
1008
1009         if ( isset($wp_registered_sidebars[$id]['description']) )
1010                 return esc_html( $wp_registered_sidebars[$id]['description'] );
1011 }
1012
1013 /**
1014  * Remove widget from sidebar.
1015  *
1016  * @since 2.2.0
1017  *
1018  * @param int|string $id Widget ID.
1019  */
1020 function wp_unregister_sidebar_widget($id) {
1021
1022         /**
1023          * Fires just before a widget is removed from a sidebar.
1024          *
1025          * @since 3.0.0
1026          *
1027          * @param int $id The widget ID.
1028          */
1029         do_action( 'wp_unregister_sidebar_widget', $id );
1030
1031         wp_register_sidebar_widget($id, '', '');
1032         wp_unregister_widget_control($id);
1033 }
1034
1035 /**
1036  * Registers widget control callback for customizing options.
1037  *
1038  * The options contains the 'height', 'width', and 'id_base' keys. The 'height'
1039  * option is never used. The 'width' option is the width of the fully expanded
1040  * control form, but try hard to use the default width. The 'id_base' is for
1041  * multi-widgets (widgets which allow multiple instances such as the text
1042  * widget), an id_base must be provided. The widget id will end up looking like
1043  * `{$id_base}-{$unique_number}`.
1044  *
1045  * @since 2.2.0
1046  *
1047  * @todo Document `$options` as a hash notation, re: WP_Widget::__construct() cross-reference.
1048  * @todo `$params` parameter?
1049  *
1050  * @global array $wp_registered_widget_controls
1051  * @global array $wp_registered_widget_updates
1052  * @global array $wp_registered_widgets
1053  * @global array $_wp_deprecated_widgets_callbacks
1054  *
1055  * @param int|string   $id               Sidebar ID.
1056  * @param string       $name             Sidebar display name.
1057  * @param callback     $control_callback Run when sidebar is displayed.
1058  * @param array|string $options          Optional. Widget options. See description above. Default empty array.
1059  */
1060 function wp_register_widget_control( $id, $name, $control_callback, $options = array() ) {
1061         global $wp_registered_widget_controls, $wp_registered_widget_updates, $wp_registered_widgets, $_wp_deprecated_widgets_callbacks;
1062
1063         $id = strtolower($id);
1064         $id_base = _get_widget_id_base($id);
1065
1066         if ( empty($control_callback) ) {
1067                 unset($wp_registered_widget_controls[$id]);
1068                 unset($wp_registered_widget_updates[$id_base]);
1069                 return;
1070         }
1071
1072         if ( in_array($control_callback, $_wp_deprecated_widgets_callbacks, true) && !is_callable($control_callback) ) {
1073                 unset( $wp_registered_widgets[ $id ] );
1074                 return;
1075         }
1076
1077         if ( isset($wp_registered_widget_controls[$id]) && !did_action( 'widgets_init' ) )
1078                 return;
1079
1080         $defaults = array('width' => 250, 'height' => 200 ); // height is never used
1081         $options = wp_parse_args($options, $defaults);
1082         $options['width'] = (int) $options['width'];
1083         $options['height'] = (int) $options['height'];
1084
1085         $widget = array(
1086                 'name' => $name,
1087                 'id' => $id,
1088                 'callback' => $control_callback,
1089                 'params' => array_slice(func_get_args(), 4)
1090         );
1091         $widget = array_merge($widget, $options);
1092
1093         $wp_registered_widget_controls[$id] = $widget;
1094
1095         if ( isset($wp_registered_widget_updates[$id_base]) )
1096                 return;
1097
1098         if ( isset($widget['params'][0]['number']) )
1099                 $widget['params'][0]['number'] = -1;
1100
1101         unset($widget['width'], $widget['height'], $widget['name'], $widget['id']);
1102         $wp_registered_widget_updates[$id_base] = $widget;
1103 }
1104
1105 /**
1106  * @global array $wp_registered_widget_updates
1107  *
1108  * @param string   $id_base
1109  * @param callable $update_callback
1110  * @param array    $options
1111  */
1112 function _register_widget_update_callback($id_base, $update_callback, $options = array()) {
1113         global $wp_registered_widget_updates;
1114
1115         if ( isset($wp_registered_widget_updates[$id_base]) ) {
1116                 if ( empty($update_callback) )
1117                         unset($wp_registered_widget_updates[$id_base]);
1118                 return;
1119         }
1120
1121         $widget = array(
1122                 'callback' => $update_callback,
1123                 'params' => array_slice(func_get_args(), 3)
1124         );
1125
1126         $widget = array_merge($widget, $options);
1127         $wp_registered_widget_updates[$id_base] = $widget;
1128 }
1129
1130 /**
1131  *
1132  * @global array $wp_registered_widget_controls
1133  *
1134  * @param int|string $id
1135  * @param string     $name
1136  * @param callable   $form_callback
1137  * @param array      $options
1138  */
1139 function _register_widget_form_callback($id, $name, $form_callback, $options = array()) {
1140         global $wp_registered_widget_controls;
1141
1142         $id = strtolower($id);
1143
1144         if ( empty($form_callback) ) {
1145                 unset($wp_registered_widget_controls[$id]);
1146                 return;
1147         }
1148
1149         if ( isset($wp_registered_widget_controls[$id]) && !did_action( 'widgets_init' ) )
1150                 return;
1151
1152         $defaults = array('width' => 250, 'height' => 200 );
1153         $options = wp_parse_args($options, $defaults);
1154         $options['width'] = (int) $options['width'];
1155         $options['height'] = (int) $options['height'];
1156
1157         $widget = array(
1158                 'name' => $name,
1159                 'id' => $id,
1160                 'callback' => $form_callback,
1161                 'params' => array_slice(func_get_args(), 4)
1162         );
1163         $widget = array_merge($widget, $options);
1164
1165         $wp_registered_widget_controls[$id] = $widget;
1166 }
1167
1168 /**
1169  * Remove control callback for widget.
1170  *
1171  * @since 2.2.0
1172  *
1173  * @param int|string $id Widget ID.
1174  */
1175 function wp_unregister_widget_control($id) {
1176         wp_register_widget_control( $id, '', '' );
1177 }
1178
1179 /**
1180  * Display dynamic sidebar.
1181  *
1182  * By default this displays the default sidebar or 'sidebar-1'. If your theme specifies the 'id' or
1183  * 'name' parameter for its registered sidebars you can pass an id or name as the $index parameter.
1184  * Otherwise, you can pass in a numerical index to display the sidebar at that index.
1185  *
1186  * @since 2.2.0
1187  *
1188  * @global array $wp_registered_sidebars
1189  * @global array $wp_registered_widgets
1190  *
1191  * @param int|string $index Optional, default is 1. Index, name or ID of dynamic sidebar.
1192  * @return bool True, if widget sidebar was found and called. False if not found or not called.
1193  */
1194 function dynamic_sidebar($index = 1) {
1195         global $wp_registered_sidebars, $wp_registered_widgets;
1196
1197         if ( is_int($index) ) {
1198                 $index = "sidebar-$index";
1199         } else {
1200                 $index = sanitize_title($index);
1201                 foreach ( (array) $wp_registered_sidebars as $key => $value ) {
1202                         if ( sanitize_title($value['name']) == $index ) {
1203                                 $index = $key;
1204                                 break;
1205                         }
1206                 }
1207         }
1208
1209         $sidebars_widgets = wp_get_sidebars_widgets();
1210         if ( empty( $wp_registered_sidebars[ $index ] ) || empty( $sidebars_widgets[ $index ] ) || ! is_array( $sidebars_widgets[ $index ] ) ) {
1211                 /** This action is documented in wp-includes/widgets.php */
1212                 do_action( 'dynamic_sidebar_before', $index, false );
1213                 /** This action is documented in wp-includes/widgets.php */
1214                 do_action( 'dynamic_sidebar_after',  $index, false );
1215                 /** This filter is documented in wp-includes/widgets.php */
1216                 return apply_filters( 'dynamic_sidebar_has_widgets', false, $index );
1217         }
1218
1219         /**
1220          * Fires before widgets are rendered in a dynamic sidebar.
1221          *
1222          * Note: The action also fires for empty sidebars, and on both the front-end
1223          * and back-end, including the Inactive Widgets sidebar on the Widgets screen.
1224          *
1225          * @since 3.9.0
1226          *
1227          * @param int|string $index       Index, name, or ID of the dynamic sidebar.
1228          * @param bool       $has_widgets Whether the sidebar is populated with widgets.
1229          *                                Default true.
1230          */
1231         do_action( 'dynamic_sidebar_before', $index, true );
1232         $sidebar = $wp_registered_sidebars[$index];
1233
1234         $did_one = false;
1235         foreach ( (array) $sidebars_widgets[$index] as $id ) {
1236
1237                 if ( !isset($wp_registered_widgets[$id]) ) continue;
1238
1239                 $params = array_merge(
1240                         array( array_merge( $sidebar, array('widget_id' => $id, 'widget_name' => $wp_registered_widgets[$id]['name']) ) ),
1241                         (array) $wp_registered_widgets[$id]['params']
1242                 );
1243
1244                 // Substitute HTML id and class attributes into before_widget
1245                 $classname_ = '';
1246                 foreach ( (array) $wp_registered_widgets[$id]['classname'] as $cn ) {
1247                         if ( is_string($cn) )
1248                                 $classname_ .= '_' . $cn;
1249                         elseif ( is_object($cn) )
1250                                 $classname_ .= '_' . get_class($cn);
1251                 }
1252                 $classname_ = ltrim($classname_, '_');
1253                 $params[0]['before_widget'] = sprintf($params[0]['before_widget'], $id, $classname_);
1254
1255                 /**
1256                  * Filter the parameters passed to a widget's display callback.
1257                  *
1258                  * Note: The filter is evaluated on both the front-end and back-end,
1259                  * including for the Inactive Widgets sidebar on the Widgets screen.
1260                  *
1261                  * @since 2.5.0
1262                  *
1263                  * @see register_sidebar()
1264                  *
1265                  * @param array $params {
1266                  *     @type array $args  {
1267                  *         An array of widget display arguments.
1268                  *
1269                  *         @type string $name          Name of the sidebar the widget is assigned to.
1270                  *         @type string $id            ID of the sidebar the widget is assigned to.
1271                  *         @type string $description   The sidebar description.
1272                  *         @type string $class         CSS class applied to the sidebar container.
1273                  *         @type string $before_widget HTML markup to prepend to each widget in the sidebar.
1274                  *         @type string $after_widget  HTML markup to append to each widget in the sidebar.
1275                  *         @type string $before_title  HTML markup to prepend to the widget title when displayed.
1276                  *         @type string $after_title   HTML markup to append to the widget title when displayed.
1277                  *         @type string $widget_id     ID of the widget.
1278                  *         @type string $widget_name   Name of the widget.
1279                  *     }
1280                  *     @type array $widget_args {
1281                  *         An array of multi-widget arguments.
1282                  *
1283                  *         @type int $number Number increment used for multiples of the same widget.
1284                  *     }
1285                  * }
1286                  */
1287                 $params = apply_filters( 'dynamic_sidebar_params', $params );
1288
1289                 $callback = $wp_registered_widgets[$id]['callback'];
1290
1291                 /**
1292                  * Fires before a widget's display callback is called.
1293                  *
1294                  * Note: The action fires on both the front-end and back-end, including
1295                  * for widgets in the Inactive Widgets sidebar on the Widgets screen.
1296                  *
1297                  * The action is not fired for empty sidebars.
1298                  *
1299                  * @since 3.0.0
1300                  *
1301                  * @param array $widget_id {
1302                  *     An associative array of widget arguments.
1303                  *
1304                  *     @type string $name                Name of the widget.
1305                  *     @type string $id                  Widget ID.
1306                  *     @type array|callback $callback    When the hook is fired on the front-end, $callback is an array
1307                  *                                       containing the widget object. Fired on the back-end, $callback
1308                  *                                       is 'wp_widget_control', see $_callback.
1309                  *     @type array          $params      An associative array of multi-widget arguments.
1310                  *     @type string         $classname   CSS class applied to the widget container.
1311                  *     @type string         $description The widget description.
1312                  *     @type array          $_callback   When the hook is fired on the back-end, $_callback is populated
1313                  *                                       with an array containing the widget object, see $callback.
1314                  * }
1315                  */
1316                 do_action( 'dynamic_sidebar', $wp_registered_widgets[ $id ] );
1317
1318                 if ( is_callable($callback) ) {
1319                         call_user_func_array($callback, $params);
1320                         $did_one = true;
1321                 }
1322         }
1323
1324         /**
1325          * Fires after widgets are rendered in a dynamic sidebar.
1326          *
1327          * Note: The action also fires for empty sidebars, and on both the front-end
1328          * and back-end, including the Inactive Widgets sidebar on the Widgets screen.
1329          *
1330          * @since 3.9.0
1331          *
1332          * @param int|string $index       Index, name, or ID of the dynamic sidebar.
1333          * @param bool       $has_widgets Whether the sidebar is populated with widgets.
1334          *                                Default true.
1335          */
1336         do_action( 'dynamic_sidebar_after', $index, true );
1337
1338         /**
1339          * Filter whether a sidebar has widgets.
1340          *
1341          * Note: The filter is also evaluated for empty sidebars, and on both the front-end
1342          * and back-end, including the Inactive Widgets sidebar on the Widgets screen.
1343          *
1344          * @since 3.9.0
1345          *
1346          * @param bool       $did_one Whether at least one widget was rendered in the sidebar.
1347          *                            Default false.
1348          * @param int|string $index   Index, name, or ID of the dynamic sidebar.
1349          */
1350         return apply_filters( 'dynamic_sidebar_has_widgets', $did_one, $index );
1351 }
1352
1353 /**
1354  * Whether widget is displayed on the front-end.
1355  *
1356  * Either $callback or $id_base can be used
1357  * $id_base is the first argument when extending WP_Widget class
1358  * Without the optional $widget_id parameter, returns the ID of the first sidebar
1359  * in which the first instance of the widget with the given callback or $id_base is found.
1360  * With the $widget_id parameter, returns the ID of the sidebar where
1361  * the widget with that callback/$id_base AND that ID is found.
1362  *
1363  * NOTE: $widget_id and $id_base are the same for single widgets. To be effective
1364  * this function has to run after widgets have initialized, at action 'init' or later.
1365  *
1366  * @since 2.2.0
1367  *
1368  * @global array $wp_registered_widgets
1369  *
1370  * @param string $callback      Optional, Widget callback to check.
1371  * @param int    $widget_id     Optional, but needed for checking. Widget ID.
1372  * @param string $id_base       Optional, the base ID of a widget created by extending WP_Widget.
1373  * @param bool   $skip_inactive Optional, whether to check in 'wp_inactive_widgets'.
1374  * @return string|false False if widget is not active or id of sidebar in which the widget is active.
1375  */
1376 function is_active_widget($callback = false, $widget_id = false, $id_base = false, $skip_inactive = true) {
1377         global $wp_registered_widgets;
1378
1379         $sidebars_widgets = wp_get_sidebars_widgets();
1380
1381         if ( is_array($sidebars_widgets) ) {
1382                 foreach ( $sidebars_widgets as $sidebar => $widgets ) {
1383                         if ( $skip_inactive && ( 'wp_inactive_widgets' === $sidebar || 'orphaned_widgets' === substr( $sidebar, 0, 16 ) ) ) {
1384                                 continue;
1385                         }
1386
1387                         if ( is_array($widgets) ) {
1388                                 foreach ( $widgets as $widget ) {
1389                                         if ( ( $callback && isset($wp_registered_widgets[$widget]['callback']) && $wp_registered_widgets[$widget]['callback'] == $callback ) || ( $id_base && _get_widget_id_base($widget) == $id_base ) ) {
1390                                                 if ( !$widget_id || $widget_id == $wp_registered_widgets[$widget]['id'] )
1391                                                         return $sidebar;
1392                                         }
1393                                 }
1394                         }
1395                 }
1396         }
1397         return false;
1398 }
1399
1400 /**
1401  * Whether the dynamic sidebar is enabled and used by theme.
1402  *
1403  * @since 2.2.0
1404  *
1405  * @global array $wp_registered_widgets
1406  * @global array $wp_registered_sidebars
1407  *
1408  * @return bool True, if using widgets. False, if not using widgets.
1409  */
1410 function is_dynamic_sidebar() {
1411         global $wp_registered_widgets, $wp_registered_sidebars;
1412         $sidebars_widgets = get_option('sidebars_widgets');
1413         foreach ( (array) $wp_registered_sidebars as $index => $sidebar ) {
1414                 if ( count($sidebars_widgets[$index]) ) {
1415                         foreach ( (array) $sidebars_widgets[$index] as $widget )
1416                                 if ( array_key_exists($widget, $wp_registered_widgets) )
1417                                         return true;
1418                 }
1419         }
1420         return false;
1421 }
1422
1423 /**
1424  * Whether a sidebar is in use.
1425  *
1426  * @since 2.8.0
1427  *
1428  * @param string|int $index Sidebar name, id or number to check.
1429  * @return bool true if the sidebar is in use, false otherwise.
1430  */
1431 function is_active_sidebar( $index ) {
1432         $index = ( is_int($index) ) ? "sidebar-$index" : sanitize_title($index);
1433         $sidebars_widgets = wp_get_sidebars_widgets();
1434         $is_active_sidebar = ! empty( $sidebars_widgets[$index] );
1435
1436         /**
1437          * Filter whether a dynamic sidebar is considered "active".
1438          *
1439          * @since 3.9.0
1440          *
1441          * @param bool       $is_active_sidebar Whether or not the sidebar should be considered "active".
1442          *                                      In other words, whether the sidebar contains any widgets.
1443          * @param int|string $index             Index, name, or ID of the dynamic sidebar.
1444          */
1445         return apply_filters( 'is_active_sidebar', $is_active_sidebar, $index );
1446 }
1447
1448 /* Internal Functions */
1449
1450 /**
1451  * Retrieve full list of sidebars and their widget instance IDs.
1452  *
1453  * Will upgrade sidebar widget list, if needed. Will also save updated list, if
1454  * needed.
1455  *
1456  * @since 2.2.0
1457  * @access private
1458  *
1459  * @global array $_wp_sidebars_widgets
1460  * @global array $sidebars_widgets
1461  *
1462  * @param bool $deprecated Not used (argument deprecated).
1463  * @return array Upgraded list of widgets to version 3 array format when called from the admin.
1464  */
1465 function wp_get_sidebars_widgets( $deprecated = true ) {
1466         if ( $deprecated !== true )
1467                 _deprecated_argument( __FUNCTION__, '2.8.1' );
1468
1469         global $_wp_sidebars_widgets, $sidebars_widgets;
1470
1471         // If loading from front page, consult $_wp_sidebars_widgets rather than options
1472         // to see if wp_convert_widget_settings() has made manipulations in memory.
1473         if ( !is_admin() ) {
1474                 if ( empty($_wp_sidebars_widgets) )
1475                         $_wp_sidebars_widgets = get_option('sidebars_widgets', array());
1476
1477                 $sidebars_widgets = $_wp_sidebars_widgets;
1478         } else {
1479                 $sidebars_widgets = get_option('sidebars_widgets', array());
1480         }
1481
1482         if ( is_array( $sidebars_widgets ) && isset($sidebars_widgets['array_version']) )
1483                 unset($sidebars_widgets['array_version']);
1484
1485         /**
1486          * Filter the list of sidebars and their widgets.
1487          *
1488          * @since 2.7.0
1489          *
1490          * @param array $sidebars_widgets An associative array of sidebars and their widgets.
1491          */
1492         return apply_filters( 'sidebars_widgets', $sidebars_widgets );
1493 }
1494
1495 /**
1496  * Set the sidebar widget option to update sidebars.
1497  *
1498  * @since 2.2.0
1499  * @access private
1500  *
1501  * @param array $sidebars_widgets Sidebar widgets and their settings.
1502  */
1503 function wp_set_sidebars_widgets( $sidebars_widgets ) {
1504         if ( !isset( $sidebars_widgets['array_version'] ) )
1505                 $sidebars_widgets['array_version'] = 3;
1506         update_option( 'sidebars_widgets', $sidebars_widgets );
1507 }
1508
1509 /**
1510  * Retrieve default registered sidebars list.
1511  *
1512  * @since 2.2.0
1513  * @access private
1514  *
1515  * @global array $wp_registered_sidebars
1516  *
1517  * @return array
1518  */
1519 function wp_get_widget_defaults() {
1520         global $wp_registered_sidebars;
1521
1522         $defaults = array();
1523
1524         foreach ( (array) $wp_registered_sidebars as $index => $sidebar )
1525                 $defaults[$index] = array();
1526
1527         return $defaults;
1528 }
1529
1530 /**
1531  * Convert the widget settings from single to multi-widget format.
1532  *
1533  * @since 2.8.0
1534  *
1535  * @global array $_wp_sidebars_widgets
1536  *
1537  * @param string $base_name
1538  * @param string $option_name
1539  * @param array  $settings
1540  * @return array
1541  */
1542 function wp_convert_widget_settings($base_name, $option_name, $settings) {
1543         // This test may need expanding.
1544         $single = $changed = false;
1545         if ( empty($settings) ) {
1546                 $single = true;
1547         } else {
1548                 foreach ( array_keys($settings) as $number ) {
1549                         if ( 'number' == $number )
1550                                 continue;
1551                         if ( !is_numeric($number) ) {
1552                                 $single = true;
1553                                 break;
1554                         }
1555                 }
1556         }
1557
1558         if ( $single ) {
1559                 $settings = array( 2 => $settings );
1560
1561                 // If loading from the front page, update sidebar in memory but don't save to options
1562                 if ( is_admin() ) {
1563                         $sidebars_widgets = get_option('sidebars_widgets');
1564                 } else {
1565                         if ( empty($GLOBALS['_wp_sidebars_widgets']) )
1566                                 $GLOBALS['_wp_sidebars_widgets'] = get_option('sidebars_widgets', array());
1567                         $sidebars_widgets = &$GLOBALS['_wp_sidebars_widgets'];
1568                 }
1569
1570                 foreach ( (array) $sidebars_widgets as $index => $sidebar ) {
1571                         if ( is_array($sidebar) ) {
1572                                 foreach ( $sidebar as $i => $name ) {
1573                                         if ( $base_name == $name ) {
1574                                                 $sidebars_widgets[$index][$i] = "$name-2";
1575                                                 $changed = true;
1576                                                 break 2;
1577                                         }
1578                                 }
1579                         }
1580                 }
1581
1582                 if ( is_admin() && $changed )
1583                         update_option('sidebars_widgets', $sidebars_widgets);
1584         }
1585
1586         $settings['_multiwidget'] = 1;
1587         if ( is_admin() )
1588                 update_option( $option_name, $settings );
1589
1590         return $settings;
1591 }
1592
1593 /**
1594  * Output an arbitrary widget as a template tag.
1595  *
1596  * @since 2.8.0
1597  *
1598  * @global WP_Widget_Factory $wp_widget_factory
1599  *
1600  * @param string $widget   The widget's PHP class name (see default-widgets.php).
1601  * @param array  $instance Optional. The widget's instance settings. Default empty array.
1602  * @param array  $args {
1603  *     Optional. Array of arguments to configure the display of the widget.
1604  *
1605  *     @type string $before_widget HTML content that will be prepended to the widget's HTML output.
1606  *                                 Default `<div class="widget %s">`, where `%s` is the widget's class name.
1607  *     @type string $after_widget  HTML content that will be appended to the widget's HTML output.
1608  *                                 Default `</div>`.
1609  *     @type string $before_title  HTML content that will be prepended to the widget's title when displayed.
1610  *                                 Default `<h2 class="widgettitle">`.
1611  *     @type string $after_title   HTML content that will be appended to the widget's title when displayed.
1612  *                                 Default `</h2>`.
1613  * }
1614  */
1615 function the_widget( $widget, $instance = array(), $args = array() ) {
1616         global $wp_widget_factory;
1617
1618         $widget_obj = $wp_widget_factory->widgets[$widget];
1619         if ( ! ( $widget_obj instanceof WP_Widget ) ) {
1620                 return;
1621         }
1622
1623         $before_widget = sprintf('<div class="widget %s">', $widget_obj->widget_options['classname'] );
1624         $default_args = array( 'before_widget' => $before_widget, 'after_widget' => "</div>", 'before_title' => '<h2 class="widgettitle">', 'after_title' => '</h2>' );
1625
1626         $args = wp_parse_args($args, $default_args);
1627         $instance = wp_parse_args($instance);
1628
1629         /**
1630          * Fires before rendering the requested widget.
1631          *
1632          * @since 3.0.0
1633          *
1634          * @param string $widget   The widget's class name.
1635          * @param array  $instance The current widget instance's settings.
1636          * @param array  $args     An array of the widget's sidebar arguments.
1637          */
1638         do_action( 'the_widget', $widget, $instance, $args );
1639
1640         $widget_obj->_set(-1);
1641         $widget_obj->widget($args, $instance);
1642 }
1643
1644 /**
1645  * Private
1646  *
1647  * @return string
1648  */
1649 function _get_widget_id_base($id) {
1650         return preg_replace( '/-[0-9]+$/', '', $id );
1651 }
1652
1653 /**
1654  * Handle sidebars config after theme change
1655  *
1656  * @access private
1657  * @since 3.3.0
1658  *
1659  * @global array $sidebars_widgets
1660  */
1661 function _wp_sidebars_changed() {
1662         global $sidebars_widgets;
1663
1664         if ( ! is_array( $sidebars_widgets ) )
1665                 $sidebars_widgets = wp_get_sidebars_widgets();
1666
1667         retrieve_widgets(true);
1668 }
1669
1670 /**
1671  * Look for "lost" widgets, this has to run at least on each theme change.
1672  *
1673  * @since 2.8.0
1674  *
1675  * @global array $wp_registered_sidebars
1676  * @global array $sidebars_widgets
1677  * @global array $wp_registered_widgets
1678  *
1679  * @param string|bool $theme_changed Whether the theme was changed as a boolean. A value
1680  *                                   of 'customize' defers updates for the Customizer.
1681  * @return array|void
1682  */
1683 function retrieve_widgets( $theme_changed = false ) {
1684         global $wp_registered_sidebars, $sidebars_widgets, $wp_registered_widgets;
1685
1686         $registered_sidebar_keys = array_keys( $wp_registered_sidebars );
1687         $orphaned = 0;
1688
1689         $old_sidebars_widgets = get_theme_mod( 'sidebars_widgets' );
1690         if ( is_array( $old_sidebars_widgets ) ) {
1691                 // time() that sidebars were stored is in $old_sidebars_widgets['time']
1692                 $_sidebars_widgets = $old_sidebars_widgets['data'];
1693
1694                 if ( 'customize' !== $theme_changed ) {
1695                         remove_theme_mod( 'sidebars_widgets' );
1696                 }
1697
1698                 foreach ( $_sidebars_widgets as $sidebar => $widgets ) {
1699                         if ( 'wp_inactive_widgets' === $sidebar || 'orphaned_widgets' === substr( $sidebar, 0, 16 ) ) {
1700                                 continue;
1701                         }
1702
1703                         if ( !in_array( $sidebar, $registered_sidebar_keys ) ) {
1704                                 $_sidebars_widgets['orphaned_widgets_' . ++$orphaned] = $widgets;
1705                                 unset( $_sidebars_widgets[$sidebar] );
1706                         }
1707                 }
1708         } else {
1709                 if ( empty( $sidebars_widgets ) )
1710                         return;
1711
1712                 unset( $sidebars_widgets['array_version'] );
1713
1714                 $old = array_keys($sidebars_widgets);
1715                 sort($old);
1716                 sort($registered_sidebar_keys);
1717
1718                 if ( $old == $registered_sidebar_keys )
1719                         return;
1720
1721                 $_sidebars_widgets = array(
1722                         'wp_inactive_widgets' => !empty( $sidebars_widgets['wp_inactive_widgets'] ) ? $sidebars_widgets['wp_inactive_widgets'] : array()
1723                 );
1724
1725                 unset( $sidebars_widgets['wp_inactive_widgets'] );
1726
1727                 foreach ( $wp_registered_sidebars as $id => $settings ) {
1728                         if ( $theme_changed ) {
1729                                 $_sidebars_widgets[$id] = array_shift( $sidebars_widgets );
1730                         } else {
1731                                 // no theme change, grab only sidebars that are currently registered
1732                                 if ( isset( $sidebars_widgets[$id] ) ) {
1733                                         $_sidebars_widgets[$id] = $sidebars_widgets[$id];
1734                                         unset( $sidebars_widgets[$id] );
1735                                 }
1736                         }
1737                 }
1738
1739                 foreach ( $sidebars_widgets as $val ) {
1740                         if ( is_array($val) && ! empty( $val ) )
1741                                 $_sidebars_widgets['orphaned_widgets_' . ++$orphaned] = $val;
1742                 }
1743         }
1744
1745         // discard invalid, theme-specific widgets from sidebars
1746         $shown_widgets = array();
1747
1748         foreach ( $_sidebars_widgets as $sidebar => $widgets ) {
1749                 if ( !is_array($widgets) )
1750                         continue;
1751
1752                 $_widgets = array();
1753                 foreach ( $widgets as $widget ) {
1754                         if ( isset($wp_registered_widgets[$widget]) )
1755                                 $_widgets[] = $widget;
1756                 }
1757
1758                 $_sidebars_widgets[$sidebar] = $_widgets;
1759                 $shown_widgets = array_merge($shown_widgets, $_widgets);
1760         }
1761
1762         $sidebars_widgets = $_sidebars_widgets;
1763         unset($_sidebars_widgets, $_widgets);
1764
1765         // find hidden/lost multi-widget instances
1766         $lost_widgets = array();
1767         foreach ( $wp_registered_widgets as $key => $val ) {
1768                 if ( in_array($key, $shown_widgets, true) )
1769                         continue;
1770
1771                 $number = preg_replace('/.+?-([0-9]+)$/', '$1', $key);
1772
1773                 if ( 2 > (int) $number )
1774                         continue;
1775
1776                 $lost_widgets[] = $key;
1777         }
1778
1779         $sidebars_widgets['wp_inactive_widgets'] = array_merge($lost_widgets, (array) $sidebars_widgets['wp_inactive_widgets']);
1780         if ( 'customize' !== $theme_changed ) {
1781                 wp_set_sidebars_widgets( $sidebars_widgets );
1782         }
1783
1784         return $sidebars_widgets;
1785 }