<?php

/**

 * Core Widgets API

 *

 * This API is used for creating dynamic sidebar without hardcoding functionality into

 * themes

 *

 * Includes both internal WordPress routines and theme-use routines.

 *

 * This functionality was found in a plugin before the WordPress 2.2 release, which

 * included it in the core from that point on.

 *

 * @link https://wordpress.org/support/article/wordpress-widgets/

 * @link https://developer.wordpress.org/themes/functionality/widgets/

 *

 * @package WordPress

 * @subpackage Widgets

 * @since 2.2.0

 */

//

// Global Variables.

//

/** @ignore */

global $wp_registered_sidebars, $wp_registered_widgets, $wp_registered_widget_controls, $wp_registered_widget_updates;

/**

 * Stores the sidebars, since many themes can have more than one.

 *

 * @global array $wp_registered_sidebars Registered sidebars.

 * @since 2.2.0

 */

$wp_registered_sidebars = array();

/**

 * Stores the registered widgets.

 *

 * @global array $wp_registered_widgets

 * @since 2.2.0

 */

$wp_registered_widgets = array();

/**

 * Stores the registered widget controls (options).

 *

 * @global array $wp_registered_widget_controls

 * @since 2.2.0

 */

$wp_registered_widget_controls = array();

/**

 * @global array $wp_registered_widget_updates

 */

$wp_registered_widget_updates = array();

/**

 * Private

 *

 * @global array $_wp_sidebars_widgets

 */

$_wp_sidebars_widgets = array();

/**

 * Private

 *

 * @global array $_wp_deprecated_widgets_callbacks

 */

$GLOBALS['_wp_deprecated_widgets_callbacks'] = array(

	'wp_widget_pages',

	'wp_widget_pages_control',

	'wp_widget_calendar',

	'wp_widget_calendar_control',

	'wp_widget_archives',

	'wp_widget_archives_control',

	'wp_widget_links',

	'wp_widget_meta',

	'wp_widget_meta_control',

	'wp_widget_search',

	'wp_widget_recent_entries',

	'wp_widget_recent_entries_control',

	'wp_widget_tag_cloud',

	'wp_widget_tag_cloud_control',

	'wp_widget_categories',

	'wp_widget_categories_control',

	'wp_widget_text',

	'wp_widget_text_control',

	'wp_widget_rss',

	'wp_widget_rss_control',

	'wp_widget_recent_comments',

	'wp_widget_recent_comments_control',

);

//

// Template tags & API functions.

//

/**

 * Register a widget

 *

 * Registers a WP_Widget widget

 *

 * @since 2.8.0

 * @since 4.6.0 Updated the `$widget` parameter to also accept a WP_Widget instance object

 *              instead of simply a `WP_Widget` subclass name.

 *

 * @see WP_Widget

 *

 * @global WP_Widget_Factory $wp_widget_factory

 *

 * @param string|WP_Widget $widget Either the name of a `WP_Widget` subclass or an instance of a `WP_Widget` subclass.

 */

function register_widget( $widget ) {

	global $wp_widget_factory;

	$wp_widget_factory->register( $widget );

}

/**

 * Unregisters a widget.

 *

 * Unregisters a WP_Widget widget. Useful for un-registering default widgets.

 * Run within a function hooked to the {@see 'widgets_init'} action.

 *

 * @since 2.8.0

 * @since 4.6.0 Updated the `$widget` parameter to also accept a WP_Widget instance object

 *              instead of simply a `WP_Widget` subclass name.

 *

 * @see WP_Widget

 *

 * @global WP_Widget_Factory $wp_widget_factory

 *

 * @param string|WP_Widget $widget Either the name of a `WP_Widget` subclass or an instance of a `WP_Widget` subclass.

 */

function unregister_widget( $widget ) {

	global $wp_widget_factory;

	$wp_widget_factory->unregister( $widget );

}

/**

 * Creates multiple sidebars.

 *

 * If you wanted to quickly create multiple sidebars for a theme or internally.

 * This function will allow you to do so. If you don't pass the 'name' and/or

 * 'id' in `$args`, then they will be built for you.

 *

 * @since 2.2.0

 *

 * @see register_sidebar() The second parameter is documented by register_sidebar() and is the same here.

 *

 * @global array $wp_registered_sidebars The new sidebars are stored in this array by sidebar ID.

 *

 * @param int          $number Optional. Number of sidebars to create. Default 1.

 * @param array|string $args {

 *     Optional. Array or string of arguments for building a sidebar.

 *

 *     @type string $id   The base string of the unique identifier for each sidebar. If provided, and multiple

 *                        sidebars are being defined, the ID will have "-2" appended, and so on.

 *                        Default 'sidebar-' followed by the number the sidebar creation is currently at.

 *     @type string $name The name or title for the sidebars displayed in the admin dashboard. If registering

 *                        more than one sidebar, include '%d' in the string as a placeholder for the uniquely

 *                        assigned number for each sidebar.

 *                        Default 'Sidebar' for the first sidebar, otherwise 'Sidebar %d'.

 * }

 */

function register_sidebars( $number = 1, $args = array() ) {

	global $wp_registered_sidebars;

	$number = (int) $number;

	if ( is_string( $args ) ) {

		parse_str( $args, $args );

	}

	for ( $i = 1; $i <= $number; $i++ ) {

		$_args = $args;

		if ( $number > 1 ) {

			if ( isset( $args['name'] ) ) {

				$_args['name'] = sprintf( $args['name'], $i );

			} else {

				/* translators: %d: Sidebar number. */

				$_args['name'] = sprintf( __( 'Sidebar %d' ), $i );

			}

		} else {

			$_args['name'] = isset( $args['name'] ) ? $args['name'] : __( 'Sidebar' );

		}

		// Custom specified ID's are suffixed if they exist already.

		// Automatically generated sidebar names need to be suffixed regardless starting at -0.

		if ( isset( $args['id'] ) ) {

			$_args['id'] = $args['id'];

			$n           = 2; // Start at -2 for conflicting custom IDs.

			while ( is_registered_sidebar( $_args['id'] ) ) {

				$_args['id'] = $args['id'] . '-' . $n++;

			}

		} else {

			$n = count( $wp_registered_sidebars );

			do {

				$_args['id'] = 'sidebar-' . ++$n;

			} while ( is_registered_sidebar( $_args['id'] ) );

		}

		register_sidebar( $_args );

	}

}

/**

 * Builds the definition for a single sidebar and returns the ID.

 *

 * Accepts either a string or an array and then parses that against a set

 * of default arguments for the new sidebar. WordPress will automatically

 * generate a sidebar ID and name based on the current number of registered

 * sidebars if those arguments are not included.

 *

 * When allowing for automatic generation of the name and ID parameters, keep

 * in mind that the incrementor for your sidebar can change over time depending

 * on what other plugins and themes are installed.

 *

 * If theme support for 'widgets' has not yet been added when this function is

 * called, it will be automatically enabled through the use of add_theme_support()

 *

 * @since 2.2.0

 * @since 5.6.0 Added the `before_sidebar` and `after_sidebar` arguments.

 *

 * @global array $wp_registered_sidebars Registered sidebars.

 *

 * @param array|string $args {

 *     Optional. Array or string of arguments for the sidebar being registered.

 *

 *     @type string $name           The name or title of the sidebar displayed in the Widgets

 *                                  interface. Default 'Sidebar $instance'.

 *     @type string $id             The unique identifier by which the sidebar will be called.

 *                                  Default 'sidebar-$instance'.

 *     @type string $description    Description of the sidebar, displayed in the Widgets interface.

 *                                  Default empty string.

 *     @type string $class          Extra CSS class to assign to the sidebar in the Widgets interface.

 *                                  Default empty.

 *     @type string $before_widget  HTML content to prepend to each widget's HTML output when assigned

 *                                  to this sidebar. Receives the widget's ID attribute as `%1$s`

 *                                  and class name as `%2$s`. Default is an opening list item element.

 *     @type string $after_widget   HTML content to append to each widget's HTML output when assigned

 *                                  to this sidebar. Default is a closing list item element.

 *     @type string $before_title   HTML content to prepend to the sidebar title when displayed.

 *                                  Default is an opening h2 element.

 *     @type string $after_title    HTML content to append to the sidebar title when displayed.

 *                                  Default is a closing h2 element.

 *     @type string $before_sidebar HTML content to prepend to the sidebar when displayed.

 *                                  Receives the `$id` argument as `%1$s` and `$class` as `%2$s`.

 *                                  Outputs after the {@see 'dynamic_sidebar_before'} action.

 *                                  Default empty string.

 *     @type string $after_sidebar  HTML content to append to the sidebar when displayed.

 *                                  Outputs before the {@see 'dynamic_sidebar_after'} action.

 *                                  Default empty string.

 * }

 * @return string Sidebar ID added to $wp_registered_sidebars global.

 */

function register_sidebar( $args = array() ) {

	global $wp_registered_sidebars;

	$i = count( $wp_registered_sidebars ) + 1;

	$id_is_empty = empty( $args['id'] );

	$defaults = array(

		/* translators: %d: Sidebar number. */

		'name'           => sprintf( __( 'Sidebar %d' ), $i ),

		'id'             => "sidebar-$i",

		'description'    => '',

		'class'          => '',

		'before_widget'  => '<li id="%1$s" class="widget %2$s">',

		'after_widget'   => "</li>\n",

		'before_title'   => '<h2 class="widgettitle">',

		'after_title'    => "</h2>\n",

		'before_sidebar' => '',

		'after_sidebar'  => '',

	);

	/**

	 * Filters the sidebar default arguments.

	 *

	 * @since 5.3.0

	 *

	 * @see register_sidebar()

	 *

	 * @param array $defaults The default sidebar arguments.

	 */

	$sidebar = wp_parse_args( $args, apply_filters( 'register_sidebar_defaults', $defaults ) );

	if ( $id_is_empty ) {

		_doing_it_wrong(

			__FUNCTION__,

			sprintf(

				/* translators: 1: The 'id' argument, 2: Sidebar name, 3: Recommended 'id' value. */

				__( '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'

		);

	}

	$wp_registered_sidebars[ $sidebar['id'] ] = $sidebar;

	add_theme_support( 'widgets' );

	/**

	 * Fires once a sidebar has been registered.

	 *

	 * @since 3.0.0

	 *

	 * @param array $sidebar Parsed arguments for the registered sidebar.

	 */

	do_action( 'register_sidebar', $sidebar );

	return $sidebar['id'];

}

/**

 * Removes a sidebar from the list.

 *

 * @since 2.2.0

 *

 * @global array $wp_registered_sidebars Registered sidebars.

 *

 * @param string|int $sidebar_id The ID of the sidebar when it was registered.

 */

function unregister_sidebar( $sidebar_id ) {

	global $wp_registered_sidebars;

	unset( $wp_registered_sidebars[ $sidebar_id ] );

}

/**

 * Checks if a sidebar is registered.

 *

 * @since 4.4.0

 *

 * @global array $wp_registered_sidebars Registered sidebars.

 *

 * @param string|int $sidebar_id The ID of the sidebar when it was registered.

 * @return bool True if the sidebar is registered, false otherwise.

 */

function is_registered_sidebar( $sidebar_id ) {

	global $wp_registered_sidebars;

	return isset( $wp_registered_sidebars[ $sidebar_id ] );

}

/**

 * Register an instance of a widget.

 *

 * The default widget option is 'classname' that can be overridden.

 *

 * The function can also be used to un-register widgets when `$output_callback`

 * parameter is an empty string.

 *

 * @since 2.2.0

 * @since 5.3.0 Formalized the existing and already documented `...$params` parameter

 *              by adding it to the function signature.

 * @since 5.8.0 Added show_instance_in_rest option.

 *

 * @global array $wp_registered_widgets            Uses stored registered widgets.

 * @global array $wp_registered_widget_controls    Stores the registered widget controls (options).

 * @global array $wp_registered_widget_updates

 * @global array $_wp_deprecated_widgets_callbacks

 *

 * @param int|string $id              Widget ID.

 * @param string     $name            Widget display title.

 * @param callable   $output_callback Run when widget is called.

 * @param array      $options {

 *     Optional. An array of supplementary widget options for the instance.

 *

 *     @type string $classname             Class name for the widget's HTML container. Default is a shortened

 *                                         version of the output callback name.

 *     @type string $description           Widget description for display in the widget administration

 *                                         panel and/or theme.

 *     @type bool   $show_instance_in_rest Whether to show the widget's instance settings in the REST API.

 *                                         Only available for WP_Widget based widgets.

 * }

 * @param mixed      ...$params       Optional additional parameters to pass to the callback function when it's called.

 */

function wp_register_sidebar_widget( $id, $name, $output_callback, $options = array(), ...$params ) {

	global $wp_registered_widgets, $wp_registered_widget_controls, $wp_registered_widget_updates, $_wp_deprecated_widgets_callbacks;

	$id = strtolower( $id );

	if ( empty( $output_callback ) ) {

		unset( $wp_registered_widgets[ $id ] );

		return;

	}

	$id_base = _get_widget_id_base( $id );

	if ( in_array( $output_callback, $_wp_deprecated_widgets_callbacks, true ) && ! is_callable( $output_callback ) ) {

		unset( $wp_registered_widget_controls[ $id ] );

		unset( $wp_registered_widget_updates[ $id_base ] );

		return;

	}

	$defaults = array( 'classname' => $output_callback );

	$options  = wp_parse_args( $options, $defaults );

	$widget   = array(

		'name'     => $name,

		'id'       => $id,

		'callback' => $output_callback,

		'params'   => $params,

	);

	$widget   = array_merge( $widget, $options );

	if ( is_callable( $output_callback ) && ( ! isset( $wp_registered_widgets[ $id ] ) || did_action( 'widgets_init' ) ) ) {

		/**

		 * Fires once for each registered widget.

		 *

		 * @since 3.0.0

		 *

		 * @param array $widget An array of default widget arguments.

		 */

		do_action( 'wp_register_sidebar_widget', $widget );

		$wp_registered_widgets[ $id ] = $widget;

	}

}

/**

 * Retrieve description for widget.

 *

 * When registering widgets, the options can also include 'description' that

 * describes the widget for display on the widget administration panel or

 * in the theme.

 *

 * @since 2.5.0

 *

 * @global array $wp_registered_widgets

 *