public/edition/wp-includes/class-wp-widget.php line 360

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