[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * REST API: WP_REST_Widget_Types_Controller class
   4   *
   5   * @package WordPress
   6   * @subpackage REST_API
   7   * @since 5.8.0
   8   */
   9  
  10  /**
  11   * Core class to access widget types via the REST API.
  12   *
  13   * @since 5.8.0
  14   *
  15   * @see WP_REST_Controller
  16   */
  17  class WP_REST_Widget_Types_Controller extends WP_REST_Controller {
  18  
  19      /**
  20       * Constructor.
  21       *
  22       * @since 5.8.0
  23       */
  24  	public function __construct() {
  25          $this->namespace = 'wp/v2';
  26          $this->rest_base = 'widget-types';
  27      }
  28  
  29      /**
  30       * Registers the widget type routes.
  31       *
  32       * @since 5.8.0
  33       *
  34       * @see register_rest_route()
  35       */
  36  	public function register_routes() {
  37          register_rest_route(
  38              $this->namespace,
  39              '/' . $this->rest_base,
  40              array(
  41                  array(
  42                      'methods'             => WP_REST_Server::READABLE,
  43                      'callback'            => array( $this, 'get_items' ),
  44                      'permission_callback' => array( $this, 'get_items_permissions_check' ),
  45                      'args'                => $this->get_collection_params(),
  46                  ),
  47                  'schema' => array( $this, 'get_public_item_schema' ),
  48              )
  49          );
  50  
  51          register_rest_route(
  52              $this->namespace,
  53              '/' . $this->rest_base . '/(?P<id>[a-zA-Z0-9_-]+)',
  54              array(
  55                  'args'   => array(
  56                      'id' => array(
  57                          'description' => __( 'The widget type id.' ),
  58                          'type'        => 'string',
  59                      ),
  60                  ),
  61                  array(
  62                      'methods'             => WP_REST_Server::READABLE,
  63                      'callback'            => array( $this, 'get_item' ),
  64                      'permission_callback' => array( $this, 'get_item_permissions_check' ),
  65                      'args'                => $this->get_collection_params(),
  66                  ),
  67                  'schema' => array( $this, 'get_public_item_schema' ),
  68              )
  69          );
  70  
  71          register_rest_route(
  72              $this->namespace,
  73              '/' . $this->rest_base . '/(?P<id>[a-zA-Z0-9_-]+)/encode',
  74              array(
  75                  'args' => array(
  76                      'id'        => array(
  77                          'description' => __( 'The widget type id.' ),
  78                          'type'        => 'string',
  79                          'required'    => true,
  80                      ),
  81                      'instance'  => array(
  82                          'description' => __( 'Current instance settings of the widget.' ),
  83                          'type'        => 'object',
  84                      ),
  85                      'form_data' => array(
  86                          'description'       => __( 'Serialized widget form data to encode into instance settings.' ),
  87                          'type'              => 'string',
  88                          'sanitize_callback' => static function ( $form_data ) {
  89                              $array = array();
  90                              wp_parse_str( $form_data, $array );
  91                              return $array;
  92                          },
  93                      ),
  94                  ),
  95                  array(
  96                      'methods'             => WP_REST_Server::CREATABLE,
  97                      'permission_callback' => array( $this, 'get_item_permissions_check' ),
  98                      'callback'            => array( $this, 'encode_form_data' ),
  99                  ),
 100              )
 101          );
 102  
 103          register_rest_route(
 104              $this->namespace,
 105              '/' . $this->rest_base . '/(?P<id>[a-zA-Z0-9_-]+)/render',
 106              array(
 107                  array(
 108                      'methods'             => WP_REST_Server::CREATABLE,
 109                      'permission_callback' => array( $this, 'get_item_permissions_check' ),
 110                      'callback'            => array( $this, 'render' ),
 111                      'args'                => array(
 112                          'id'       => array(
 113                              'description' => __( 'The widget type id.' ),
 114                              'type'        => 'string',
 115                              'required'    => true,
 116                          ),
 117                          'instance' => array(
 118                              'description' => __( 'Current instance settings of the widget.' ),
 119                              'type'        => 'object',
 120                          ),
 121                      ),
 122                  ),
 123              )
 124          );
 125      }
 126  
 127      /**
 128       * Checks whether a given request has permission to read widget types.
 129       *
 130       * @since 5.8.0
 131       *
 132       * @param WP_REST_Request $request Full details about the request.
 133       * @return true|WP_Error True if the request has read access, WP_Error object otherwise.
 134       */
 135  	public function get_items_permissions_check( $request ) {
 136          return $this->check_read_permission();
 137      }
 138  
 139      /**
 140       * Retrieves the list of all widget types.
 141       *
 142       * @since 5.8.0
 143       *
 144       * @param WP_REST_Request $request Full details about the request.
 145       * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 146       */
 147  	public function get_items( $request ) {
 148          if ( $request->is_method( 'HEAD' ) ) {
 149              // Return early as this handler doesn't add any response headers.
 150              return new WP_REST_Response( array() );
 151          }
 152  
 153          $data = array();
 154          foreach ( $this->get_widgets() as $widget ) {
 155              $widget_type = $this->prepare_item_for_response( $widget, $request );
 156              $data[]      = $this->prepare_response_for_collection( $widget_type );
 157          }
 158  
 159          return rest_ensure_response( $data );
 160      }
 161  
 162      /**
 163       * Checks if a given request has access to read a widget type.
 164       *
 165       * @since 5.8.0
 166       *
 167       * @param WP_REST_Request $request Full details about the request.
 168       * @return true|WP_Error True if the request has read access for the item, WP_Error object otherwise.
 169       */
 170  	public function get_item_permissions_check( $request ) {
 171          $check = $this->check_read_permission();
 172          if ( is_wp_error( $check ) ) {
 173              return $check;
 174          }
 175          $widget_id   = $request['id'];
 176          $widget_type = $this->get_widget( $widget_id );
 177          if ( is_wp_error( $widget_type ) ) {
 178              return $widget_type;
 179          }
 180  
 181          return true;
 182      }
 183  
 184      /**
 185       * Checks whether the user can read widget types.
 186       *
 187       * @since 5.8.0
 188       *
 189       * @return true|WP_Error True if the widget type is visible, WP_Error otherwise.
 190       */
 191  	protected function check_read_permission() {
 192          if ( ! current_user_can( 'edit_theme_options' ) ) {
 193              return new WP_Error(
 194                  'rest_cannot_manage_widgets',
 195                  __( 'Sorry, you are not allowed to manage widgets on this site.' ),
 196                  array(
 197                      'status' => rest_authorization_required_code(),
 198                  )
 199              );
 200          }
 201  
 202          return true;
 203      }
 204  
 205      /**
 206       * Gets the details about the requested widget.
 207       *
 208       * @since 5.8.0
 209       *
 210       * @param string $id The widget type id.
 211       * @return array|WP_Error The array of widget data if the name is valid, WP_Error otherwise.
 212       */
 213  	public function get_widget( $id ) {
 214          foreach ( $this->get_widgets() as $widget ) {
 215              if ( $id === $widget['id'] ) {
 216                  return $widget;
 217              }
 218          }
 219  
 220          return new WP_Error( 'rest_widget_type_invalid', __( 'Invalid widget type.' ), array( 'status' => 404 ) );
 221      }
 222  
 223      /**
 224       * Normalize array of widgets.
 225       *
 226       * @since 5.8.0
 227       *
 228       * @global WP_Widget_Factory $wp_widget_factory
 229       * @global array             $wp_registered_widgets The list of registered widgets.
 230       *
 231       * @return array Array of widgets.
 232       */
 233  	protected function get_widgets() {
 234          global $wp_widget_factory, $wp_registered_widgets;
 235  
 236          $widgets = array();
 237  
 238          foreach ( $wp_registered_widgets as $widget ) {
 239              $parsed_id     = wp_parse_widget_id( $widget['id'] );
 240              $widget_object = $wp_widget_factory->get_widget_object( $parsed_id['id_base'] );
 241  
 242              $widget['id']       = $parsed_id['id_base'];
 243              $widget['is_multi'] = (bool) $widget_object;
 244  
 245              if ( isset( $widget['name'] ) ) {
 246                  $widget['name'] = html_entity_decode( $widget['name'], ENT_QUOTES, get_bloginfo( 'charset' ) );
 247              }
 248  
 249              if ( isset( $widget['description'] ) ) {
 250                  $widget['description'] = html_entity_decode( $widget['description'], ENT_QUOTES, get_bloginfo( 'charset' ) );
 251              }
 252  
 253              unset( $widget['callback'] );
 254  
 255              $classname = '';
 256              foreach ( (array) $widget['classname'] as $cn ) {
 257                  if ( is_string( $cn ) ) {
 258                      $classname .= '_' . $cn;
 259                  } elseif ( is_object( $cn ) ) {
 260                      $classname .= '_' . get_class( $cn );
 261                  }
 262              }
 263              $widget['classname'] = ltrim( $classname, '_' );
 264  
 265              $widgets[ $widget['id'] ] = $widget;
 266          }
 267  
 268          ksort( $widgets );
 269  
 270          return $widgets;
 271      }
 272  
 273      /**
 274       * Retrieves a single widget type from the collection.
 275       *
 276       * @since 5.8.0
 277       *
 278       * @param WP_REST_Request $request Full details about the request.
 279       * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 280       */
 281  	public function get_item( $request ) {
 282          $widget_id   = $request['id'];
 283          $widget_type = $this->get_widget( $widget_id );
 284          if ( is_wp_error( $widget_type ) ) {
 285              return $widget_type;
 286          }
 287          $data = $this->prepare_item_for_response( $widget_type, $request );
 288  
 289          return rest_ensure_response( $data );
 290      }
 291  
 292      /**
 293       * Prepares a widget type object for serialization.
 294       *
 295       * @since 5.8.0
 296       * @since 5.9.0 Renamed `$widget_type` to `$item` to match parent class for PHP 8 named parameter support.
 297       *
 298       * @param array           $item    Widget type data.
 299       * @param WP_REST_Request $request Full details about the request.
 300       * @return WP_REST_Response Widget type data.
 301       */
 302  	public function prepare_item_for_response( $item, $request ) {
 303          // Restores the more descriptive, specific name for use within this method.
 304          $widget_type = $item;
 305  
 306          // Don't prepare the response body for HEAD requests.
 307          if ( $request->is_method( 'HEAD' ) ) {
 308              /** This filter is documented in wp-includes/rest-api/endpoints/class-wp-rest-widget-types-controller.php */
 309              return apply_filters( 'rest_prepare_widget_type', new WP_REST_Response( array() ), $widget_type, $request );
 310          }
 311  
 312          $fields = $this->get_fields_for_response( $request );
 313          $data   = array(
 314              'id' => $widget_type['id'],
 315          );
 316  
 317          $schema       = $this->get_item_schema();
 318          $extra_fields = array(
 319              'name',
 320              'description',
 321              'is_multi',
 322              'classname',
 323              'widget_class',
 324              'option_name',
 325              'customize_selective_refresh',
 326          );
 327  
 328          foreach ( $extra_fields as $extra_field ) {
 329              if ( ! rest_is_field_included( $extra_field, $fields ) ) {
 330                  continue;
 331              }
 332  
 333              if ( isset( $widget_type[ $extra_field ] ) ) {
 334                  $field = $widget_type[ $extra_field ];
 335              } elseif ( array_key_exists( 'default', $schema['properties'][ $extra_field ] ) ) {
 336                  $field = $schema['properties'][ $extra_field ]['default'];
 337              } else {
 338                  $field = '';
 339              }
 340  
 341              $data[ $extra_field ] = rest_sanitize_value_from_schema( $field, $schema['properties'][ $extra_field ] );
 342          }
 343  
 344          $context = ! empty( $request['context'] ) ? $request['context'] : 'view';
 345          $data    = $this->add_additional_fields_to_object( $data, $request );
 346          $data    = $this->filter_response_by_context( $data, $context );
 347  
 348          $response = rest_ensure_response( $data );
 349  
 350          if ( rest_is_field_included( '_links', $fields ) || rest_is_field_included( '_embedded', $fields ) ) {
 351              $response->add_links( $this->prepare_links( $widget_type ) );
 352          }
 353  
 354          /**
 355           * Filters the REST API response for a widget type.
 356           *
 357           * @since 5.8.0
 358           *
 359           * @param WP_REST_Response $response    The response object.
 360           * @param array            $widget_type The array of widget data.
 361           * @param WP_REST_Request  $request     The request object.
 362           */
 363          return apply_filters( 'rest_prepare_widget_type', $response, $widget_type, $request );
 364      }
 365  
 366      /**
 367       * Prepares links for the widget type.
 368       *
 369       * @since 5.8.0
 370       *
 371       * @param array $widget_type Widget type data.
 372       * @return array Links for the given widget type.
 373       */
 374  	protected function prepare_links( $widget_type ) {
 375          return array(
 376              'collection' => array(
 377                  'href' => rest_url( sprintf( '%s/%s', $this->namespace, $this->rest_base ) ),
 378              ),
 379              'self'       => array(
 380                  'href' => rest_url( sprintf( '%s/%s/%s', $this->namespace, $this->rest_base, $widget_type['id'] ) ),
 381              ),
 382          );
 383      }
 384  
 385      /**
 386       * Retrieves the widget type's schema, conforming to JSON Schema.
 387       *
 388       * @since 5.8.0
 389       *
 390       * @return array Item schema data.
 391       */
 392  	public function get_item_schema() {
 393          if ( $this->schema ) {
 394              return $this->add_additional_fields_schema( $this->schema );
 395          }
 396  
 397          $schema = array(
 398              '$schema'    => 'http://json-schema.org/draft-04/schema#',
 399              'title'      => 'widget-type',
 400              'type'       => 'object',
 401              'properties' => array(
 402                  'id'          => array(
 403                      'description' => __( 'Unique slug identifying the widget type.' ),
 404                      'type'        => 'string',
 405                      'context'     => array( 'embed', 'view', 'edit' ),
 406                      'readonly'    => true,
 407                  ),
 408                  'name'        => array(
 409                      'description' => __( 'Human-readable name identifying the widget type.' ),
 410                      'type'        => 'string',
 411                      'default'     => '',
 412                      'context'     => array( 'embed', 'view', 'edit' ),
 413                      'readonly'    => true,
 414                  ),
 415                  'description' => array(
 416                      'description' => __( 'Description of the widget.' ),
 417                      'type'        => 'string',
 418                      'default'     => '',
 419                      'context'     => array( 'view', 'edit', 'embed' ),
 420                  ),
 421                  'is_multi'    => array(
 422                      'description' => __( 'Whether the widget supports multiple instances' ),
 423                      'type'        => 'boolean',
 424                      'context'     => array( 'view', 'edit', 'embed' ),
 425                      'readonly'    => true,
 426                  ),
 427                  'classname'   => array(
 428                      'description' => __( 'Class name' ),
 429                      'type'        => 'string',
 430                      'default'     => '',
 431                      'context'     => array( 'embed', 'view', 'edit' ),
 432                      'readonly'    => true,
 433                  ),
 434              ),
 435          );
 436  
 437          $this->schema = $schema;
 438  
 439          return $this->add_additional_fields_schema( $this->schema );
 440      }
 441  
 442      /**
 443       * An RPC-style endpoint which can be used by clients to turn user input in
 444       * a widget admin form into an encoded instance object.
 445       *
 446       * Accepts:
 447       *
 448       * - id:        A widget type ID.
 449       * - instance:  A widget's encoded instance object. Optional.
 450       * - form_data: Form data from submitting a widget's admin form. Optional.
 451       *
 452       * Returns:
 453       * - instance: The encoded instance object after updating the widget with
 454       *             the given form data.
 455       * - form:     The widget's admin form after updating the widget with the
 456       *             given form data.
 457       *
 458       * @since 5.8.0
 459       *
 460       * @global WP_Widget_Factory $wp_widget_factory
 461       *
 462       * @param WP_REST_Request $request Full details about the request.
 463       * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 464       */
 465  	public function encode_form_data( $request ) {
 466          global $wp_widget_factory;
 467  
 468          $id            = $request['id'];
 469          $widget_object = $wp_widget_factory->get_widget_object( $id );
 470  
 471          if ( ! $widget_object ) {
 472              return new WP_Error(
 473                  'rest_invalid_widget',
 474                  __( 'Cannot preview a widget that does not extend WP_Widget.' ),
 475                  array( 'status' => 400 )
 476              );
 477          }
 478  
 479          /*
 480           * Set the widget's number so that the id attributes in the HTML that we
 481           * return are predictable.
 482           */
 483          if ( isset( $request['number'] ) && is_numeric( $request['number'] ) ) {
 484              $widget_object->_set( (int) $request['number'] );
 485          } else {
 486              $widget_object->_set( -1 );
 487          }
 488  
 489          if ( isset( $request['instance']['encoded'], $request['instance']['hash'] ) ) {
 490              $serialized_instance = base64_decode( $request['instance']['encoded'] );
 491              if ( ! hash_equals( wp_hash( $serialized_instance ), $request['instance']['hash'] ) ) {
 492                  return new WP_Error(
 493                      'rest_invalid_widget',
 494                      __( 'The provided instance is malformed.' ),
 495                      array( 'status' => 400 )
 496                  );
 497              }
 498              $instance = unserialize( $serialized_instance );
 499          } else {
 500              $instance = array();
 501          }
 502  
 503          if (
 504              isset( $request['form_data'][ "widget-$id" ] ) &&
 505              is_array( $request['form_data'][ "widget-$id" ] )
 506          ) {
 507              $new_instance = array_values( $request['form_data'][ "widget-$id" ] )[0];
 508              $old_instance = $instance;
 509  
 510              $instance = $widget_object->update( $new_instance, $old_instance );
 511  
 512              /** This filter is documented in wp-includes/class-wp-widget.php */
 513              $instance = apply_filters(
 514                  'widget_update_callback',
 515                  $instance,
 516                  $new_instance,
 517                  $old_instance,
 518                  $widget_object
 519              );
 520          }
 521  
 522          $serialized_instance = serialize( $instance );
 523          $widget_key          = $wp_widget_factory->get_widget_key( $id );
 524  
 525          $response = array(
 526              'form'     => trim(
 527                  $this->get_widget_form(
 528                      $widget_object,
 529                      $instance
 530                  )
 531              ),
 532              'preview'  => trim(
 533                  $this->get_widget_preview(
 534                      $widget_key,
 535                      $instance
 536                  )
 537              ),
 538              'instance' => array(
 539                  'encoded' => base64_encode( $serialized_instance ),
 540                  'hash'    => wp_hash( $serialized_instance ),
 541              ),
 542          );
 543  
 544          if ( ! empty( $widget_object->widget_options['show_instance_in_rest'] ) ) {
 545              // Use new stdClass so that JSON result is {} and not [].
 546              $response['instance']['raw'] = empty( $instance ) ? new stdClass() : $instance;
 547          }
 548  
 549          return rest_ensure_response( $response );
 550      }
 551  
 552      /**
 553       * Returns the output of WP_Widget::widget() when called with the provided
 554       * instance. Used by encode_form_data() to preview a widget.
 555  
 556       * @since 5.8.0
 557       *
 558       * @param string    $widget   The widget's PHP class name (see class-wp-widget.php).
 559       * @param array     $instance Widget instance settings.
 560       * @return string
 561       */
 562  	private function get_widget_preview( $widget, $instance ) {
 563          ob_start();
 564          the_widget( $widget, $instance );
 565          return ob_get_clean();
 566      }
 567  
 568      /**
 569       * Returns the output of WP_Widget::form() when called with the provided
 570       * instance. Used by encode_form_data() to preview a widget's form.
 571       *
 572       * @since 5.8.0
 573       *
 574       * @param WP_Widget $widget_object Widget object to call widget() on.
 575       * @param array     $instance Widget instance settings.
 576       * @return string
 577       */
 578  	private function get_widget_form( $widget_object, $instance ) {
 579          ob_start();
 580  
 581          /** This filter is documented in wp-includes/class-wp-widget.php */
 582          $instance = apply_filters(
 583              'widget_form_callback',
 584              $instance,
 585              $widget_object
 586          );
 587  
 588          if ( false !== $instance ) {
 589              $return = $widget_object->form( $instance );
 590  
 591              /** This filter is documented in wp-includes/class-wp-widget.php */
 592              do_action_ref_array(
 593                  'in_widget_form',
 594                  array( &$widget_object, &$return, $instance )
 595              );
 596          }
 597  
 598          return ob_get_clean();
 599      }
 600  
 601      /**
 602       * Renders a single Legacy Widget and wraps it in a JSON-encodable array.
 603       *
 604       * @since 5.9.0
 605       *
 606       * @param WP_REST_Request $request Full details about the request.
 607       *
 608       * @return array An array with rendered Legacy Widget HTML.
 609       */
 610  	public function render( $request ) {
 611          return array(
 612              'preview' => $this->render_legacy_widget_preview_iframe(
 613                  $request['id'],
 614                  isset( $request['instance'] ) ? $request['instance'] : null
 615              ),
 616          );
 617      }
 618  
 619      /**
 620       * Renders a page containing a preview of the requested Legacy Widget block.
 621       *
 622       * @since 5.9.0
 623       *
 624       * @param string $id_base The id base of the requested widget.
 625       * @param array  $instance The widget instance attributes.
 626       *
 627       * @return string Rendered Legacy Widget block preview.
 628       */
 629  	private function render_legacy_widget_preview_iframe( $id_base, $instance ) {
 630          if ( ! defined( 'IFRAME_REQUEST' ) ) {
 631              define( 'IFRAME_REQUEST', true );
 632          }
 633  
 634          ob_start();
 635          ?>
 636          <!doctype html>
 637          <html <?php language_attributes(); ?>>
 638          <head>
 639              <meta charset="<?php bloginfo( 'charset' ); ?>" />
 640              <meta name="viewport" content="width=device-width, initial-scale=1" />
 641              <link rel="profile" href="https://gmpg.org/xfn/11" />
 642              <?php wp_head(); ?>
 643              <style>
 644                  /* Reset theme styles */
 645                  html, body, #page, #content {
 646                      padding: 0 !important;
 647                      margin: 0 !important;
 648                  }
 649              </style>
 650          </head>
 651          <body <?php body_class(); ?>>
 652          <div id="page" class="site">
 653              <div id="content" class="site-content">
 654                  <?php
 655                  $registry = WP_Block_Type_Registry::get_instance();
 656                  $block    = $registry->get_registered( 'core/legacy-widget' );
 657                  echo $block->render(
 658                      array(
 659                          'idBase'   => $id_base,
 660                          'instance' => $instance,
 661                      )
 662                  );
 663                  ?>
 664              </div><!-- #content -->
 665          </div><!-- #page -->
 666          <?php wp_footer(); ?>
 667          </body>
 668          </html>
 669          <?php
 670          return ob_get_clean();
 671      }
 672  
 673      /**
 674       * Retrieves the query params for collections.
 675       *
 676       * @since 5.8.0
 677       *
 678       * @return array Collection parameters.
 679       */
 680  	public function get_collection_params() {
 681          return array(
 682              'context' => $this->get_context_param( array( 'default' => 'view' ) ),
 683          );
 684      }
 685  }