wp_register_widget_control

The timeline below displays how wordpress function wp_register_widget_control has changed across different WordPress versions. If a version is not listed, refer to the next available version below.

WordPress Version: 6.5

/**
 * Registers widget control callback for customizing options.
 *
 * @since 2.2.0
 * @since 5.3.0 Formalized the existing and already documented `...$params` parameter
 *              by adding it to the function signature.
 *
 * @global array $wp_registered_widget_controls The registered widget controls.
 * @global array $wp_registered_widget_updates  The registered widget updates.
 * @global array $wp_registered_widgets         The registered widgets.
 * @global array $_wp_deprecated_widgets_callbacks
 *
 * @param int|string $id               Sidebar ID.
 * @param string     $name             Sidebar display name.
 * @param callable   $control_callback Run when sidebar is displayed.
 * @param array      $options {
 *     Optional. Array or string of control options. Default empty array.
 *
 *     @type int        $height  Never used. Default 200.
 *     @type int        $width   Width of the fully expanded control form (but try hard to use the default width).
 *                               Default 250.
 *     @type int|string $id_base Required for multi-widgets, i.e widgets that allow multiple instances such as the
 *                               text widget. The widget ID will end up looking like `{$id_base}-{$unique_number}`.
 * }
 * @param mixed      ...$params        Optional additional parameters to pass to the callback function when it's called.
 */
function wp_register_widget_control($id, $name, $control_callback, $options = array(), ...$params)
{
    global $wp_registered_widget_controls, $wp_registered_widget_updates, $wp_registered_widgets, $_wp_deprecated_widgets_callbacks;
    $id = strtolower($id);
    $id_base = _get_widget_id_base($id);
    if (empty($control_callback)) {
        unset($wp_registered_widget_controls[$id]);
        unset($wp_registered_widget_updates[$id_base]);
        return;
    }
    if (in_array($control_callback, $_wp_deprecated_widgets_callbacks, true) && !is_callable($control_callback)) {
        unset($wp_registered_widgets[$id]);
        return;
    }
    if (isset($wp_registered_widget_controls[$id]) && !did_action('widgets_init')) {
        return;
    }
    $defaults = array('width' => 250, 'height' => 200);
    // Height is never used.
    $options = wp_parse_args($options, $defaults);
    $options['width'] = (int) $options['width'];
    $options['height'] = (int) $options['height'];
    $widget = array('name' => $name, 'id' => $id, 'callback' => $control_callback, 'params' => $params);
    $widget = array_merge($widget, $options);
    $wp_registered_widget_controls[$id] = $widget;
    if (isset($wp_registered_widget_updates[$id_base])) {
        return;
    }
    if (isset($widget['params'][0]['number'])) {
        $widget['params'][0]['number'] = -1;
    }
    unset($widget['width'], $widget['height'], $widget['name'], $widget['id']);
    $wp_registered_widget_updates[$id_base] = $widget;
}

WordPress Version: 5.9

/**
 * Registers widget control callback for customizing options.
 *
 * @since 2.2.0
 * @since 5.3.0 Formalized the existing and already documented `...$params` parameter
 *              by adding it to the function signature.
 *
 * @global array $wp_registered_widget_controls
 * @global array $wp_registered_widget_updates
 * @global array $wp_registered_widgets
 * @global array $_wp_deprecated_widgets_callbacks
 *
 * @param int|string $id               Sidebar ID.
 * @param string     $name             Sidebar display name.
 * @param callable   $control_callback Run when sidebar is displayed.
 * @param array      $options {
 *     Optional. Array or string of control options. Default empty array.
 *
 *     @type int        $height  Never used. Default 200.
 *     @type int        $width   Width of the fully expanded control form (but try hard to use the default width).
 *                               Default 250.
 *     @type int|string $id_base Required for multi-widgets, i.e widgets that allow multiple instances such as the
 *                               text widget. The widget ID will end up looking like `{$id_base}-{$unique_number}`.
 * }
 * @param mixed      ...$params        Optional additional parameters to pass to the callback function when it's called.
 */
function wp_register_widget_control($id, $name, $control_callback, $options = array(), ...$params)
{
    global $wp_registered_widget_controls, $wp_registered_widget_updates, $wp_registered_widgets, $_wp_deprecated_widgets_callbacks;
    $id = strtolower($id);
    $id_base = _get_widget_id_base($id);
    if (empty($control_callback)) {
        unset($wp_registered_widget_controls[$id]);
        unset($wp_registered_widget_updates[$id_base]);
        return;
    }
    if (in_array($control_callback, $_wp_deprecated_widgets_callbacks, true) && !is_callable($control_callback)) {
        unset($wp_registered_widgets[$id]);
        return;
    }
    if (isset($wp_registered_widget_controls[$id]) && !did_action('widgets_init')) {
        return;
    }
    $defaults = array('width' => 250, 'height' => 200);
    // Height is never used.
    $options = wp_parse_args($options, $defaults);
    $options['width'] = (int) $options['width'];
    $options['height'] = (int) $options['height'];
    $widget = array('name' => $name, 'id' => $id, 'callback' => $control_callback, 'params' => $params);
    $widget = array_merge($widget, $options);
    $wp_registered_widget_controls[$id] = $widget;
    if (isset($wp_registered_widget_updates[$id_base])) {
        return;
    }
    if (isset($widget['params'][0]['number'])) {
        $widget['params'][0]['number'] = -1;
    }
    unset($widget['width'], $widget['height'], $widget['name'], $widget['id']);
    $wp_registered_widget_updates[$id_base] = $widget;
}

WordPress Version: 5.4

/**
 * Registers widget control callback for customizing options.
 *
 * @since 2.2.0
 * @since 5.3.0 Formalized the existing and already documented `...$params` parameter
 *              by adding it to the function signature.
 *
 * @global array $wp_registered_widget_controls
 * @global array $wp_registered_widget_updates
 * @global array $wp_registered_widgets
 * @global array $_wp_deprecated_widgets_callbacks
 *
 * @param int|string $id               Sidebar ID.
 * @param string     $name             Sidebar display name.
 * @param callable   $control_callback Run when sidebar is displayed.
 * @param array      $options {
 *     Optional. Array or string of control options. Default empty array.
 *
 *     @type int        $height  Never used. Default 200.
 *     @type int        $width   Width of the fully expanded control form (but try hard to use the default width).
 *                               Default 250.
 *     @type int|string $id_base Required for multi-widgets, i.e widgets that allow multiple instances such as the
 *                               text widget. The widget id will end up looking like `{$id_base}-{$unique_number}`.
 * }
 * @param mixed      ...$params        Optional additional parameters to pass to the callback function when it's called.
 */
function wp_register_widget_control($id, $name, $control_callback, $options = array(), ...$params)
{
    global $wp_registered_widget_controls, $wp_registered_widget_updates, $wp_registered_widgets, $_wp_deprecated_widgets_callbacks;
    $id = strtolower($id);
    $id_base = _get_widget_id_base($id);
    if (empty($control_callback)) {
        unset($wp_registered_widget_controls[$id]);
        unset($wp_registered_widget_updates[$id_base]);
        return;
    }
    if (in_array($control_callback, $_wp_deprecated_widgets_callbacks, true) && !is_callable($control_callback)) {
        unset($wp_registered_widgets[$id]);
        return;
    }
    if (isset($wp_registered_widget_controls[$id]) && !did_action('widgets_init')) {
        return;
    }
    $defaults = array('width' => 250, 'height' => 200);
    // Height is never used.
    $options = wp_parse_args($options, $defaults);
    $options['width'] = (int) $options['width'];
    $options['height'] = (int) $options['height'];
    $widget = array('name' => $name, 'id' => $id, 'callback' => $control_callback, 'params' => $params);
    $widget = array_merge($widget, $options);
    $wp_registered_widget_controls[$id] = $widget;
    if (isset($wp_registered_widget_updates[$id_base])) {
        return;
    }
    if (isset($widget['params'][0]['number'])) {
        $widget['params'][0]['number'] = -1;
    }
    unset($widget['width'], $widget['height'], $widget['name'], $widget['id']);
    $wp_registered_widget_updates[$id_base] = $widget;
}

WordPress Version: 5.3

/**
 * Registers widget control callback for customizing options.
 *
 * @since 2.2.0
 * @since 5.3.0 Formalized the existing and already documented `...$params` parameter
 *              by adding it to the function signature.
 *
 * @global array $wp_registered_widget_controls
 * @global array $wp_registered_widget_updates
 * @global array $wp_registered_widgets
 * @global array $_wp_deprecated_widgets_callbacks
 *
 * @param int|string $id               Sidebar ID.
 * @param string     $name             Sidebar display name.
 * @param callable   $control_callback Run when sidebar is displayed.
 * @param array      $options {
 *     Optional. Array or string of control options. Default empty array.
 *
 *     @type int        $height  Never used. Default 200.
 *     @type int        $width   Width of the fully expanded control form (but try hard to use the default width).
 *                               Default 250.
 *     @type int|string $id_base Required for multi-widgets, i.e widgets that allow multiple instances such as the
 *                               text widget. The widget id will end up looking like `{$id_base}-{$unique_number}`.
 * }
 * @param mixed      ...$params        Optional additional parameters to pass to the callback function when it's called.
 */
function wp_register_widget_control($id, $name, $control_callback, $options = array(), ...$params)
{
    global $wp_registered_widget_controls, $wp_registered_widget_updates, $wp_registered_widgets, $_wp_deprecated_widgets_callbacks;
    $id = strtolower($id);
    $id_base = _get_widget_id_base($id);
    if (empty($control_callback)) {
        unset($wp_registered_widget_controls[$id]);
        unset($wp_registered_widget_updates[$id_base]);
        return;
    }
    if (in_array($control_callback, $_wp_deprecated_widgets_callbacks, true) && !is_callable($control_callback)) {
        unset($wp_registered_widgets[$id]);
        return;
    }
    if (isset($wp_registered_widget_controls[$id]) && !did_action('widgets_init')) {
        return;
    }
    $defaults = array('width' => 250, 'height' => 200);
    // height is never used
    $options = wp_parse_args($options, $defaults);
    $options['width'] = (int) $options['width'];
    $options['height'] = (int) $options['height'];
    $widget = array('name' => $name, 'id' => $id, 'callback' => $control_callback, 'params' => $params);
    $widget = array_merge($widget, $options);
    $wp_registered_widget_controls[$id] = $widget;
    if (isset($wp_registered_widget_updates[$id_base])) {
        return;
    }
    if (isset($widget['params'][0]['number'])) {
        $widget['params'][0]['number'] = -1;
    }
    unset($widget['width'], $widget['height'], $widget['name'], $widget['id']);
    $wp_registered_widget_updates[$id_base] = $widget;
}

WordPress Version: 4.5

/**
 * Registers widget control callback for customizing options.
 *
 * @since 2.2.0
 *
 * @todo `$params` parameter?
 *
 * @global array $wp_registered_widget_controls
 * @global array $wp_registered_widget_updates
 * @global array $wp_registered_widgets
 * @global array $_wp_deprecated_widgets_callbacks
 *
 * @param int|string   $id               Sidebar ID.
 * @param string       $name             Sidebar display name.
 * @param callable     $control_callback Run when sidebar is displayed.
 * @param array $options {
 *     Optional. Array or string of control options. Default empty array.
 *
 *     @type int        $height  Never used. Default 200.
 *     @type int        $width   Width of the fully expanded control form (but try hard to use the default width).
 *                               Default 250.
 *     @type int|string $id_base Required for multi-widgets, i.e widgets that allow multiple instances such as the
 *                               text widget. The widget id will end up looking like `{$id_base}-{$unique_number}`.
 * }
 */
function wp_register_widget_control($id, $name, $control_callback, $options = array())
{
    global $wp_registered_widget_controls, $wp_registered_widget_updates, $wp_registered_widgets, $_wp_deprecated_widgets_callbacks;
    $id = strtolower($id);
    $id_base = _get_widget_id_base($id);
    if (empty($control_callback)) {
        unset($wp_registered_widget_controls[$id]);
        unset($wp_registered_widget_updates[$id_base]);
        return;
    }
    if (in_array($control_callback, $_wp_deprecated_widgets_callbacks, true) && !is_callable($control_callback)) {
        unset($wp_registered_widgets[$id]);
        return;
    }
    if (isset($wp_registered_widget_controls[$id]) && !did_action('widgets_init')) {
        return;
    }
    $defaults = array('width' => 250, 'height' => 200);
    // height is never used
    $options = wp_parse_args($options, $defaults);
    $options['width'] = (int) $options['width'];
    $options['height'] = (int) $options['height'];
    $widget = array('name' => $name, 'id' => $id, 'callback' => $control_callback, 'params' => array_slice(func_get_args(), 4));
    $widget = array_merge($widget, $options);
    $wp_registered_widget_controls[$id] = $widget;
    if (isset($wp_registered_widget_updates[$id_base])) {
        return;
    }
    if (isset($widget['params'][0]['number'])) {
        $widget['params'][0]['number'] = -1;
    }
    unset($widget['width'], $widget['height'], $widget['name'], $widget['id']);
    $wp_registered_widget_updates[$id_base] = $widget;
}

WordPress Version: 4.4

/**
 * Registers widget control callback for customizing options.
 *
 * The options contains the 'height', 'width', and 'id_base' keys. The 'height'
 * option is never used. The 'width' option is the width of the fully expanded
 * control form, but try hard to use the default width. The 'id_base' is for
 * multi-widgets (widgets which allow multiple instances such as the text
 * widget), an id_base must be provided. The widget id will end up looking like
 * `{$id_base}-{$unique_number}`.
 *
 * @since 2.2.0
 *
 * @todo Document `$options` as a hash notation, re: WP_Widget::__construct() cross-reference.
 * @todo `$params` parameter?
 *
 * @global array $wp_registered_widget_controls
 * @global array $wp_registered_widget_updates
 * @global array $wp_registered_widgets
 * @global array $_wp_deprecated_widgets_callbacks
 *
 * @param int|string   $id               Sidebar ID.
 * @param string       $name             Sidebar display name.
 * @param callable     $control_callback Run when sidebar is displayed.
 * @param array|string $options          Optional. Widget options. See description above. Default empty array.
 */
function wp_register_widget_control($id, $name, $control_callback, $options = array())
{
    global $wp_registered_widget_controls, $wp_registered_widget_updates, $wp_registered_widgets, $_wp_deprecated_widgets_callbacks;
    $id = strtolower($id);
    $id_base = _get_widget_id_base($id);
    if (empty($control_callback)) {
        unset($wp_registered_widget_controls[$id]);
        unset($wp_registered_widget_updates[$id_base]);
        return;
    }
    if (in_array($control_callback, $_wp_deprecated_widgets_callbacks, true) && !is_callable($control_callback)) {
        unset($wp_registered_widgets[$id]);
        return;
    }
    if (isset($wp_registered_widget_controls[$id]) && !did_action('widgets_init')) {
        return;
    }
    $defaults = array('width' => 250, 'height' => 200);
    // height is never used
    $options = wp_parse_args($options, $defaults);
    $options['width'] = (int) $options['width'];
    $options['height'] = (int) $options['height'];
    $widget = array('name' => $name, 'id' => $id, 'callback' => $control_callback, 'params' => array_slice(func_get_args(), 4));
    $widget = array_merge($widget, $options);
    $wp_registered_widget_controls[$id] = $widget;
    if (isset($wp_registered_widget_updates[$id_base])) {
        return;
    }
    if (isset($widget['params'][0]['number'])) {
        $widget['params'][0]['number'] = -1;
    }
    unset($widget['width'], $widget['height'], $widget['name'], $widget['id']);
    $wp_registered_widget_updates[$id_base] = $widget;
}

WordPress Version: 4.3

/**
 * Registers widget control callback for customizing options.
 *
 * The options contains the 'height', 'width', and 'id_base' keys. The 'height'
 * option is never used. The 'width' option is the width of the fully expanded
 * control form, but try hard to use the default width. The 'id_base' is for
 * multi-widgets (widgets which allow multiple instances such as the text
 * widget), an id_base must be provided. The widget id will end up looking like
 * `{$id_base}-{$unique_number}`.
 *
 * @since 2.2.0
 *
 * @todo Document `$options` as a hash notation, re: WP_Widget::__construct() cross-reference.
 * @todo `$params` parameter?
 *
 * @global array $wp_registered_widget_controls
 * @global array $wp_registered_widget_updates
 * @global array $wp_registered_widgets
 * @global array $_wp_deprecated_widgets_callbacks
 *
 * @param int|string   $id               Sidebar ID.
 * @param string       $name             Sidebar display name.
 * @param callback     $control_callback Run when sidebar is displayed.
 * @param array|string $options          Optional. Widget options. See description above. Default empty array.
 */
function wp_register_widget_control($id, $name, $control_callback, $options = array())
{
    global $wp_registered_widget_controls, $wp_registered_widget_updates, $wp_registered_widgets, $_wp_deprecated_widgets_callbacks;
    $id = strtolower($id);
    $id_base = _get_widget_id_base($id);
    if (empty($control_callback)) {
        unset($wp_registered_widget_controls[$id]);
        unset($wp_registered_widget_updates[$id_base]);
        return;
    }
    if (in_array($control_callback, $_wp_deprecated_widgets_callbacks, true) && !is_callable($control_callback)) {
        unset($wp_registered_widgets[$id]);
        return;
    }
    if (isset($wp_registered_widget_controls[$id]) && !did_action('widgets_init')) {
        return;
    }
    $defaults = array('width' => 250, 'height' => 200);
    // height is never used
    $options = wp_parse_args($options, $defaults);
    $options['width'] = (int) $options['width'];
    $options['height'] = (int) $options['height'];
    $widget = array('name' => $name, 'id' => $id, 'callback' => $control_callback, 'params' => array_slice(func_get_args(), 4));
    $widget = array_merge($widget, $options);
    $wp_registered_widget_controls[$id] = $widget;
    if (isset($wp_registered_widget_updates[$id_base])) {
        return;
    }
    if (isset($widget['params'][0]['number'])) {
        $widget['params'][0]['number'] = -1;
    }
    unset($widget['width'], $widget['height'], $widget['name'], $widget['id']);
    $wp_registered_widget_updates[$id_base] = $widget;
}

WordPress Version: 4.1

/**
 * Registers widget control callback for customizing options.
 *
 * The options contains the 'height', 'width', and 'id_base' keys. The 'height'
 * option is never used. The 'width' option is the width of the fully expanded
 * control form, but try hard to use the default width. The 'id_base' is for
 * multi-widgets (widgets which allow multiple instances such as the text
 * widget), an id_base must be provided. The widget id will end up looking like
 * `{$id_base}-{$unique_number}`.
 *
 * @since 2.2.0
 *
 * @todo Document `$options` as a hash notation, re: WP_Widget::__construct() cross-reference.
 * @todo `$params` parameter?
 *
 * @param int|string   $id               Sidebar ID.
 * @param string       $name             Sidebar display name.
 * @param callback     $control_callback Run when sidebar is displayed.
 * @param array|string $options          Optional. Widget options. See description above. Default empty array.
 */
function wp_register_widget_control($id, $name, $control_callback, $options = array())
{
    global $wp_registered_widget_controls, $wp_registered_widget_updates, $wp_registered_widgets, $_wp_deprecated_widgets_callbacks;
    $id = strtolower($id);
    $id_base = _get_widget_id_base($id);
    if (empty($control_callback)) {
        unset($wp_registered_widget_controls[$id]);
        unset($wp_registered_widget_updates[$id_base]);
        return;
    }
    if (in_array($control_callback, $_wp_deprecated_widgets_callbacks, true) && !is_callable($control_callback)) {
        if (isset($wp_registered_widgets[$id])) {
            unset($wp_registered_widgets[$id]);
        }
        return;
    }
    if (isset($wp_registered_widget_controls[$id]) && !did_action('widgets_init')) {
        return;
    }
    $defaults = array('width' => 250, 'height' => 200);
    // height is never used
    $options = wp_parse_args($options, $defaults);
    $options['width'] = (int) $options['width'];
    $options['height'] = (int) $options['height'];
    $widget = array('name' => $name, 'id' => $id, 'callback' => $control_callback, 'params' => array_slice(func_get_args(), 4));
    $widget = array_merge($widget, $options);
    $wp_registered_widget_controls[$id] = $widget;
    if (isset($wp_registered_widget_updates[$id_base])) {
        return;
    }
    if (isset($widget['params'][0]['number'])) {
        $widget['params'][0]['number'] = -1;
    }
    unset($widget['width'], $widget['height'], $widget['name'], $widget['id']);
    $wp_registered_widget_updates[$id_base] = $widget;
}

WordPress Version: 3.7

/**
 * Registers widget control callback for customizing options.
 *
 * The options contains the 'height', 'width', and 'id_base' keys. The 'height'
 * option is never used. The 'width' option is the width of the fully expanded
 * control form, but try hard to use the default width. The 'id_base' is for
 * multi-widgets (widgets which allow multiple instances such as the text
 * widget), an id_base must be provided. The widget id will end up looking like
 * {$id_base}-{$unique_number}.
 *
 * @since 2.2.0
 *
 * @param int|string $id Sidebar ID.
 * @param string $name Sidebar display name.
 * @param callback $control_callback Run when sidebar is displayed.
 * @param array|string $options Optional. Widget options. See above long description.
 * @param mixed $params,... Optional. Additional parameters to add to widget.
 */
function wp_register_widget_control($id, $name, $control_callback, $options = array())
{
    global $wp_registered_widget_controls, $wp_registered_widget_updates, $wp_registered_widgets, $_wp_deprecated_widgets_callbacks;
    $id = strtolower($id);
    $id_base = _get_widget_id_base($id);
    if (empty($control_callback)) {
        unset($wp_registered_widget_controls[$id]);
        unset($wp_registered_widget_updates[$id_base]);
        return;
    }
    if (in_array($control_callback, $_wp_deprecated_widgets_callbacks, true) && !is_callable($control_callback)) {
        if (isset($wp_registered_widgets[$id])) {
            unset($wp_registered_widgets[$id]);
        }
        return;
    }
    if (isset($wp_registered_widget_controls[$id]) && !did_action('widgets_init')) {
        return;
    }
    $defaults = array('width' => 250, 'height' => 200);
    // height is never used
    $options = wp_parse_args($options, $defaults);
    $options['width'] = (int) $options['width'];
    $options['height'] = (int) $options['height'];
    $widget = array('name' => $name, 'id' => $id, 'callback' => $control_callback, 'params' => array_slice(func_get_args(), 4));
    $widget = array_merge($widget, $options);
    $wp_registered_widget_controls[$id] = $widget;
    if (isset($wp_registered_widget_updates[$id_base])) {
        return;
    }
    if (isset($widget['params'][0]['number'])) {
        $widget['params'][0]['number'] = -1;
    }
    unset($widget['width'], $widget['height'], $widget['name'], $widget['id']);
    $wp_registered_widget_updates[$id_base] = $widget;
}