<?php
/**
* Widget API: WP_Widget base class
*
* @package WordPress
* @subpackage Widgets
* @since 4.4.0
*/
/**
* Core base class extended to register widgets.
*
* This class must be extended for each widget, and WP_Widget::widget() must be overridden.
*
* If adding widget options, WP_Widget::update() and WP_Widget::form() should also be overridden.
*
* @since 2.8.0
* @since 4.4.0 Moved to its own file from wp-includes/widgets.php
*/
#[AllowDynamicProperties]
class WP_Widget {
/**
* Root ID for all widgets of this type.
*
* @since 2.8.0
* @var mixed|string
*/
public $id_base;
/**
* Name for this widget type.
*
* @since 2.8.0
* @var string
*/
public $name;
/**
* Option name for this widget type.
*
* @since 2.8.0
* @var string
*/
public $option_name;
/**
* Alt option name for this widget type.
*
* @since 2.8.0
* @var string
*/
public $alt_option_name;
/**
* Option array passed to wp_register_sidebar_widget().
*
* @since 2.8.0
* @var array
*/
public $widget_options;
/**
* Option array passed to wp_register_widget_control().
*
* @since 2.8.0
* @var array
*/
public $control_options;
/**
* Unique ID number of the current instance.
*
* @since 2.8.0
* @var bool|int
*/
public $number = false;
/**
* Unique ID string of the current instance (id_base-number).
*
* @since 2.8.0
* @var bool|string
*/
public $id = false;
/**
* Whether the widget data has been updated.
*
* Set to true when the data is updated after a POST submit - ensures it does
* not happen twice.
*
* @since 2.8.0
* @var bool
*/
public $updated = false;
//
// Member functions that must be overridden by subclasses.
//
/**
* Echoes the widget content.
*
* Subclasses should override this function to generate their widget code.
*
* @since 2.8.0
*
* @param array $args Display arguments including 'before_title', 'after_title',
* 'before_widget', and 'after_widget'.
* @param array $instance The settings for the particular instance of the widget.
*/
public function widget( $args, $instance ) {
die( 'function WP_Widget::widget() must be overridden in a subclass.' );
}
/**
* Updates a particular instance of a widget.
*
* This function should check that `$new_instance` is set correctly. The newly-calculated
* value of `$instance` should be returned. If false is returned, the instance won't be
* saved/updated.
*
* @since 2.8.0
*
* @param array $new_instance New settings for this instance as input by the user via
* WP_Widget::form().
* @param array $old_instance Old settings for this instance.
* @return array Settings to save or bool false to cancel saving.
*/
public function update( $new_instance, $old_instance ) {
return $new_instance;
}
/**
* Outputs the settings update form.
*
* @since 2.8.0
*
* @param array $instance The settings for the particular instance of the widget.
* @return string|void Default return is 'noform'.
*/
public function form( $instance ) {
echo '<p class="no-options-widget">' . __( 'There are no options for this widget.' ) . '</p>';
return 'noform';
}
// Functions you'll need to call.
/**
* PHP5 constructor.
*
* @since 2.8.0
*
* @param string $id_base Base ID for the widget, lowercase and unique. If left empty,
* a portion of the widget's PHP class name will be used. Has to be unique.
* @param string $name Name for the widget displayed on the configuration page.
* @param array $widget_options Optional. Widget options. See wp_register_sidebar_widget() for
* information on accepted arguments. Default empty array.
* @param array $control_options Optional. Widget control options. See wp_register_widget_control() for
* information on accepted arguments. Default empty array.
*/
public function __construct( $id_base, $name, $widget_options = array(), $control_options = array() ) {
if ( ! empty( $id_base ) ) {
$id_base = strtolower( $id_base );
} else {
$id_base = preg_replace( '/(wp_)?widget_/', '', strtolower( get_class( $this ) ) );
}
$this->id_base = $id_base;
$this->name = $name;
$this->option_name = 'widget_' . $this->id_base;
$this->widget_options = wp_parse_args(
$widget_options,
array(
'classname' => str_replace( '\\', '_', $this->option_name ),
'customize_selective_refresh' => false,
)
);
$this->control_options = wp_parse_args( $control_options, array( 'id_base' => $this->id_base ) );
}
/**
* PHP4 constructor.
*
* @since 2.8.0
* @deprecated 4.3.0 Use __construct() instead.
*
* @see WP_Widget::__construct()
*
* @param string $id_base Base ID for the widget, lowercase and unique. If left empty,
* a portion of the widget's PHP class name will be used. Has to be unique.
* @param string $name Name for the widget displayed on the configuration page.
* @param array $widget_options Optional. Widget options. See wp_register_sidebar_widget() for
* information on accepted arguments. Default empty array.
* @param array $control_options Optional. Widget control options. See wp_register_widget_control() for
* information on accepted arguments. Default empty array.
*/
public function WP_Widget( $id_base, $name, $widget_options = array(), $control_options = array() ) {
_deprecated_constructor( 'WP_Widget', '4.3.0', get_class( $this ) );
WP_Widget::__construct( $id_base, $name, $widget_options, $control_options );
}
/**
* Constructs name attributes for use in form() fields
*
* This function should be used in form() methods to create name attributes for fields
* to be saved by update()
*
* @since 2.8.0
* @since 4.4.0 Array format field names are now accepted.
*
* @param string $field_name Field name.
* @return string Name attribute for `$field_name`.
*/
public function get_field_name( $field_name ) {
$pos = strpos( $field_name, '[' );
if ( false !== $pos ) {
// Replace the first occurrence of '[' with ']['.
$field_name = '[' . substr_replace( $field_name, '][', $pos, strlen( '[' ) );
} else {
$field_name = '[' . $field_name . ']';
}
return 'widget-' . $this->id_base . '[' . $this->number . ']' . $field_name;
}
/**
* Constructs id attributes for use in WP_Widget::form() fields.
*
* This function should be used in form() methods to create id attributes
* for fields to be saved by WP_Widget::update().
*
* @since 2.8.0
* @since 4.4.0 Array format field IDs are now accepted.
*
* @param string $field_name Field name.
* @return string ID attribute for `$field_name`.
*/
public function get_field_id( $field_name ) {
$field_name = str_replace( array( '[]', '[', ']' ), array( '', '-', '' ), $field_name );
$field_name = trim( $field_name, '-' );
return 'widget-' . $this->id_base . '-' . $this->number . '-' . $field_name;
}
/**
* Register all widget instances of this widget class.
*
* @since 2.8.0
*/
public function _register() {
$settings = $this->get_settings();
$empty = true;
// When $settings is an array-like object, get an intrinsic array for use with array_keys().
if ( $settings instanceof ArrayObject || $settings instanceof ArrayIterator ) {
$settings = $settings->getArrayCopy();
}
if ( is_array( $settings ) ) {
foreach ( array_keys( $settings ) as $number ) {
if ( is_numeric( $number ) ) {
$this->_set( $number );
$this->_register_one( $number );
$empty = false;
}
}
}
if ( $empty ) {
// If there are none, we register the widget's existence with a generic template.
$this->_set( 1 );
$this->_register_one();
}
}
/**
* Sets the internal order number for the widget instance.
*
* @since 2.8.0
*
* @param int $number The unique order number of this widget instance compared to other
*