[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Widget API: WP_Widget_Factory class
   4   *
   5   * @package WordPress
   6   * @subpackage Widgets
   7   * @since 4.4.0
   8   */
   9  
  10  /**
  11   * Singleton that registers and instantiates WP_Widget classes.
  12   *
  13   * @since 2.8.0
  14   * @since 4.4.0 Moved to its own file from wp-includes/widgets.php
  15   */
  16  #[AllowDynamicProperties]
  17  class WP_Widget_Factory {
  18  
  19      /**
  20       * Prefix for the key under which a widget registered as an instance is stored.
  21       *
  22       * Without it the key would be the decimal representation of an integer, which PHP casts from
  23       * string to int when it is used as an array key.
  24       *
  25       * @since 7.1.1
  26       */
  27      private const INSTANCE_KEY_PREFIX = 'spl_object_id:';
  28  
  29      /**
  30       * Widgets array.
  31       *
  32       * Keyed by class name for a widget registered by name, and by a prefixed object ID for a widget
  33       * registered as an instance.
  34       *
  35       * @since 2.8.0
  36       * @var array<string, WP_Widget>
  37       * @phpstan-var array<non-decimal-int-string, WP_Widget>
  38       */
  39      public $widgets = array();
  40  
  41      /**
  42       * PHP5 constructor.
  43       *
  44       * @since 4.3.0
  45       */
  46  	public function __construct() {
  47          add_action( 'widgets_init', array( $this, '_register_widgets' ), 100 );
  48      }
  49  
  50      /**
  51       * PHP4 constructor.
  52       *
  53       * @since 2.8.0
  54       * @deprecated 4.3.0 Use __construct() instead.
  55       *
  56       * @see WP_Widget_Factory::__construct()
  57       */
  58  	public function WP_Widget_Factory() {
  59          _deprecated_constructor( 'WP_Widget_Factory', '4.3.0' );
  60          self::__construct();
  61      }
  62  
  63      /**
  64       * Registers a widget subclass.
  65       *
  66       * @since 2.8.0
  67       * @since 4.6.0 Updated the `$widget` parameter to also accept a WP_Widget instance object
  68       *              instead of simply a `WP_Widget` subclass name.
  69       * @since 7.1.1 The key for an instance is prefixed so that it is never cast to an integer.
  70       *
  71       * @param string|WP_Widget $widget Either the name of a `WP_Widget` subclass or an instance of a `WP_Widget` subclass.
  72       */
  73  	public function register( $widget ) {
  74          if ( $widget instanceof WP_Widget ) {
  75              $this->widgets[ self::INSTANCE_KEY_PREFIX . spl_object_id( $widget ) ] = $widget;
  76          } else {
  77              $this->widgets[ $widget ] = new $widget();
  78          }
  79      }
  80  
  81      /**
  82       * Un-registers a widget subclass.
  83       *
  84       * @since 2.8.0
  85       * @since 4.6.0 Updated the `$widget` parameter to also accept a WP_Widget instance object
  86       *              instead of simply a `WP_Widget` subclass name.
  87       * @since 7.1.1 The key for an instance is prefixed so that it is never cast to an integer.
  88       *
  89       * @param string|WP_Widget $widget Either the name of a `WP_Widget` subclass or an instance of a `WP_Widget` subclass.
  90       */
  91  	public function unregister( $widget ) {
  92          if ( $widget instanceof WP_Widget ) {
  93              unset( $this->widgets[ self::INSTANCE_KEY_PREFIX . spl_object_id( $widget ) ] );
  94          } else {
  95              unset( $this->widgets[ $widget ] );
  96          }
  97      }
  98  
  99      /**
 100       * Serves as a utility method for adding widgets to the registered widgets global.
 101       *
 102       * @since 2.8.0
 103       *
 104       * @global array $wp_registered_widgets
 105       */
 106  	public function _register_widgets() {
 107          global $wp_registered_widgets;
 108          $keys       = array_keys( $this->widgets );
 109          $registered = array_keys( $wp_registered_widgets );
 110          $registered = array_map( '_get_widget_id_base', $registered );
 111  
 112          foreach ( $keys as $key ) {
 113              // Don't register new widget if old widget with the same id is already registered.
 114              if ( in_array( $this->widgets[ $key ]->id_base, $registered, true ) ) {
 115                  unset( $this->widgets[ $key ] );
 116                  continue;
 117              }
 118  
 119              $this->widgets[ $key ]->_register();
 120          }
 121      }
 122  
 123      /**
 124       * Returns the registered WP_Widget object for the given widget type.
 125       *
 126       * @since 5.8.0
 127       *
 128       * @param string $id_base Widget type ID.
 129       * @return WP_Widget|null
 130       */
 131  	public function get_widget_object( $id_base ) {
 132          $key = $this->get_widget_key( $id_base );
 133          if ( '' === $key ) {
 134              return null;
 135          }
 136  
 137          return $this->widgets[ $key ];
 138      }
 139  
 140      /**
 141       * Returns the registered key for the given widget type.
 142       *
 143       * @since 5.8.0
 144       *
 145       * @param string $id_base Widget type ID.
 146       * @return string
 147       */
 148  	public function get_widget_key( $id_base ) {
 149          foreach ( $this->widgets as $key => $widget_object ) {
 150              if ( $widget_object->id_base === $id_base ) {
 151                  return $key;
 152              }
 153          }
 154  
 155          return '';
 156      }
 157  }