[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * REST API: WP_REST_Sidebars_Controller class
   4   *
   5   * Original code from {@link https://github.com/martin-pettersson/wp-rest-api-sidebars Martin Pettersson (martin_pettersson@outlook.com)}.
   6   *
   7   * @package WordPress
   8   * @subpackage REST_API
   9   * @since 5.8.0
  10   */
  11  
  12  /**
  13   * Core class used to manage a site's sidebars.
  14   *
  15   * @since 5.8.0
  16   *
  17   * @see WP_REST_Controller
  18   */
  19  class WP_REST_Sidebars_Controller extends WP_REST_Controller {
  20  
  21      /**
  22       * Tracks whether {@see retrieve_widgets()} has been called in the current request.
  23       *
  24       * @since 5.9.0
  25       * @var bool
  26       */
  27      protected $widgets_retrieved = false;
  28  
  29      /**
  30       * Sidebars controller constructor.
  31       *
  32       * @since 5.8.0
  33       */
  34  	public function __construct() {
  35          $this->namespace = 'wp/v2';
  36          $this->rest_base = 'sidebars';
  37      }
  38  
  39      /**
  40       * Registers the controllers routes.
  41       *
  42       * @since 5.8.0
  43       */
  44  	public function register_routes() {
  45          register_rest_route(
  46              $this->namespace,
  47              '/' . $this->rest_base,
  48              array(
  49                  array(
  50                      'methods'             => WP_REST_Server::READABLE,
  51                      'callback'            => array( $this, 'get_items' ),
  52                      'permission_callback' => array( $this, 'get_items_permissions_check' ),
  53                      'args'                => array(
  54                          'context' => $this->get_context_param( array( 'default' => 'view' ) ),
  55                      ),
  56                  ),
  57                  'schema' => array( $this, 'get_public_item_schema' ),
  58              )
  59          );
  60  
  61          register_rest_route(
  62              $this->namespace,
  63              '/' . $this->rest_base . '/(?P<id>[\w-]+)',
  64              array(
  65                  array(
  66                      'methods'             => WP_REST_Server::READABLE,
  67                      'callback'            => array( $this, 'get_item' ),
  68                      'permission_callback' => array( $this, 'get_item_permissions_check' ),
  69                      'args'                => array(
  70                          'id'      => array(
  71                              'description' => __( 'The id of a registered sidebar' ),
  72                              'type'        => 'string',
  73                          ),
  74                          'context' => $this->get_context_param( array( 'default' => 'view' ) ),
  75                      ),
  76                  ),
  77                  array(
  78                      'methods'             => WP_REST_Server::EDITABLE,
  79                      'callback'            => array( $this, 'update_item' ),
  80                      'permission_callback' => array( $this, 'update_item_permissions_check' ),
  81                      'args'                => $this->get_endpoint_args_for_item_schema( WP_REST_Server::EDITABLE ),
  82                  ),
  83                  'schema' => array( $this, 'get_public_item_schema' ),
  84              )
  85          );
  86      }
  87  
  88      /**
  89       * Checks if a given request has access to get sidebars.
  90       *
  91       * @since 5.8.0
  92       *
  93       * @param WP_REST_Request $request Full details about the request.
  94       * @return true|WP_Error True if the request has read access, WP_Error object otherwise.
  95       */
  96  	public function get_items_permissions_check( $request ) {
  97          $this->retrieve_widgets();
  98          foreach ( wp_get_sidebars_widgets() as $id => $widgets ) {
  99              $sidebar = $this->get_sidebar( $id );
 100  
 101              if ( ! $sidebar ) {
 102                  continue;
 103              }
 104  
 105              if ( $this->check_read_permission( $sidebar ) ) {
 106                  return true;
 107              }
 108          }
 109  
 110          return $this->do_permissions_check();
 111      }
 112  
 113      /**
 114       * Retrieves the list of sidebars (active or inactive).
 115       *
 116       * @since 5.8.0
 117       *
 118       * @param WP_REST_Request $request Full details about the request.
 119       * @return WP_REST_Response Response object on success.
 120       */
 121  	public function get_items( $request ) {
 122          if ( $request->is_method( 'HEAD' ) ) {
 123              // Return early as this handler doesn't add any response headers.
 124              return new WP_REST_Response( array() );
 125          }
 126  
 127          $this->retrieve_widgets();
 128  
 129          $data              = array();
 130          $permissions_check = $this->do_permissions_check();
 131  
 132          foreach ( wp_get_sidebars_widgets() as $id => $widgets ) {
 133              $sidebar = $this->get_sidebar( $id );
 134  
 135              if ( ! $sidebar ) {
 136                  continue;
 137              }
 138  
 139              if ( is_wp_error( $permissions_check ) && ! $this->check_read_permission( $sidebar ) ) {
 140                  continue;
 141              }
 142  
 143              $data[] = $this->prepare_response_for_collection(
 144                  $this->prepare_item_for_response( $sidebar, $request )
 145              );
 146          }
 147  
 148          return rest_ensure_response( $data );
 149      }
 150  
 151      /**
 152       * Checks if a given request has access to get a single sidebar.
 153       *
 154       * @since 5.8.0
 155       *
 156       * @param WP_REST_Request $request Full details about the request.
 157       * @return true|WP_Error True if the request has read access, WP_Error object otherwise.
 158       */
 159  	public function get_item_permissions_check( $request ) {
 160          $this->retrieve_widgets();
 161  
 162          $sidebar = $this->get_sidebar( $request['id'] );
 163          if ( $sidebar && $this->check_read_permission( $sidebar ) ) {
 164              return true;
 165          }
 166  
 167          return $this->do_permissions_check();
 168      }
 169  
 170      /**
 171       * Checks if a sidebar can be read publicly.
 172       *
 173       * @since 5.9.0
 174       *
 175       * @param array $sidebar The registered sidebar configuration.
 176       * @return bool Whether the side can be read.
 177       */
 178  	protected function check_read_permission( $sidebar ) {
 179          return ! empty( $sidebar['show_in_rest'] );
 180      }
 181  
 182      /**
 183       * Retrieves one sidebar from the collection.
 184       *
 185       * @since 5.8.0
 186       *
 187       * @param WP_REST_Request $request Full details about the request.
 188       * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 189       */
 190  	public function get_item( $request ) {
 191          $this->retrieve_widgets();
 192  
 193          $sidebar = $this->get_sidebar( $request['id'] );
 194          if ( ! $sidebar ) {
 195              return new WP_Error( 'rest_sidebar_not_found', __( 'No sidebar exists with that id.' ), array( 'status' => 404 ) );
 196          }
 197  
 198          return $this->prepare_item_for_response( $sidebar, $request );
 199      }
 200  
 201      /**
 202       * Checks if a given request has access to update sidebars.
 203       *
 204       * @since 5.8.0
 205       *
 206       * @param WP_REST_Request $request Full details about the request.
 207       * @return true|WP_Error True if the request has read access, WP_Error object otherwise.
 208       */
 209  	public function update_item_permissions_check( $request ) {
 210          return $this->do_permissions_check();
 211      }
 212  
 213      /**
 214       * Updates a sidebar.
 215       *
 216       * @since 5.8.0
 217       *
 218       * @param WP_REST_Request $request Full details about the request.
 219       * @return WP_REST_Response Response object on success, or WP_Error object on failure.
 220       */
 221  	public function update_item( $request ) {
 222          if ( isset( $request['widgets'] ) ) {
 223              $sidebars = wp_get_sidebars_widgets();
 224  
 225              foreach ( $sidebars as $sidebar_id => $widgets ) {
 226                  foreach ( $widgets as $i => $widget_id ) {
 227                      // This automatically removes the passed widget IDs from any other sidebars in use.
 228                      if ( $sidebar_id !== $request['id'] && in_array( $widget_id, $request['widgets'], true ) ) {
 229                          unset( $sidebars[ $sidebar_id ][ $i ] );
 230                      }
 231  
 232                      // This automatically removes omitted widget IDs to the inactive sidebar.
 233                      if ( $sidebar_id === $request['id'] && ! in_array( $widget_id, $request['widgets'], true ) ) {
 234                          $sidebars['wp_inactive_widgets'][] = $widget_id;
 235                      }
 236                  }
 237              }
 238  
 239              $sidebars[ $request['id'] ] = $request['widgets'];
 240  
 241              wp_set_sidebars_widgets( $sidebars );
 242          }
 243  
 244          $request['context'] = 'edit';
 245  
 246          $sidebar = $this->get_sidebar( $request['id'] );
 247  
 248          /**
 249           * Fires after a sidebar is updated via the REST API.
 250           *
 251           * @since 5.8.0
 252           *
 253           * @param array           $sidebar The updated sidebar.
 254           * @param WP_REST_Request $request Request object.
 255           */
 256          do_action( 'rest_save_sidebar', $sidebar, $request );
 257  
 258          return $this->prepare_item_for_response( $sidebar, $request );
 259      }
 260  
 261      /**
 262       * Checks if the user has permissions to make the request.
 263       *
 264       * @since 5.8.0
 265       *
 266       * @return true|WP_Error True if the request has read access, WP_Error object otherwise.
 267       */
 268  	protected function do_permissions_check() {
 269          /*
 270           * Verify if the current user has edit_theme_options capability.
 271           * This capability is required to access the widgets screen.
 272           */
 273          if ( ! current_user_can( 'edit_theme_options' ) ) {
 274              return new WP_Error(
 275                  'rest_cannot_manage_widgets',
 276                  __( 'Sorry, you are not allowed to manage widgets on this site.' ),
 277                  array( 'status' => rest_authorization_required_code() )
 278              );
 279          }
 280  
 281          return true;
 282      }
 283  
 284      /**
 285       * Retrieves the registered sidebar with the given id.
 286       *
 287       * @since 5.8.0
 288       *
 289       * @param string|int $id ID of the sidebar.
 290       * @return array|null The discovered sidebar, or null if it is not registered.
 291       */
 292  	protected function get_sidebar( $id ) {
 293          return wp_get_sidebar( $id );
 294      }
 295  
 296      /**
 297       * Looks for "lost" widgets once per request.
 298       *
 299       * @since 5.9.0
 300       *
 301       * @see retrieve_widgets()
 302       */
 303  	protected function retrieve_widgets() {
 304          if ( ! $this->widgets_retrieved ) {
 305              retrieve_widgets();
 306              $this->widgets_retrieved = true;
 307          }
 308      }
 309  
 310      /**
 311       * Prepares a single sidebar output for response.
 312       *
 313       * @since 5.8.0
 314       * @since 5.9.0 Renamed `$raw_sidebar` to `$item` to match parent class for PHP 8 named parameter support.
 315       *
 316       * @global array $wp_registered_sidebars The registered sidebars.
 317       * @global array $wp_registered_widgets  The registered widgets.
 318       *
 319       * @param array           $item    Sidebar instance.
 320       * @param WP_REST_Request $request Full details about the request.
 321       * @return WP_REST_Response Prepared response object.
 322       */
 323  	public function prepare_item_for_response( $item, $request ) {
 324          global $wp_registered_sidebars, $wp_registered_widgets;
 325  
 326          // Restores the more descriptive, specific name for use within this method.
 327          $raw_sidebar = $item;
 328  
 329          // Don't prepare the response body for HEAD requests.
 330          if ( $request->is_method( 'HEAD' ) ) {
 331              /** This filter is documented in wp-includes/rest-api/endpoints/class-wp-rest-sidebars-controller.php */
 332              return apply_filters( 'rest_prepare_sidebar', new WP_REST_Response( array() ), $raw_sidebar, $request );
 333          }
 334  
 335          $id      = $raw_sidebar['id'];
 336          $sidebar = array( 'id' => $id );
 337  
 338          if ( isset( $wp_registered_sidebars[ $id ] ) ) {
 339              $registered_sidebar = $wp_registered_sidebars[ $id ];
 340  
 341              $sidebar['status']        = 'active';
 342              $sidebar['name']          = isset( $registered_sidebar['name'] ) ? $registered_sidebar['name'] : '';
 343              $sidebar['description']   = isset( $registered_sidebar['description'] ) ? wp_sidebar_description( $id ) : '';
 344              $sidebar['class']         = isset( $registered_sidebar['class'] ) ? $registered_sidebar['class'] : '';
 345              $sidebar['before_widget'] = isset( $registered_sidebar['before_widget'] ) ? $registered_sidebar['before_widget'] : '';
 346              $sidebar['after_widget']  = isset( $registered_sidebar['after_widget'] ) ? $registered_sidebar['after_widget'] : '';
 347              $sidebar['before_title']  = isset( $registered_sidebar['before_title'] ) ? $registered_sidebar['before_title'] : '';
 348              $sidebar['after_title']   = isset( $registered_sidebar['after_title'] ) ? $registered_sidebar['after_title'] : '';
 349          } else {
 350              $sidebar['status']      = 'inactive';
 351              $sidebar['name']        = $raw_sidebar['name'];
 352              $sidebar['description'] = '';
 353              $sidebar['class']       = '';
 354          }
 355  
 356          if ( wp_is_block_theme() ) {
 357              $sidebar['status'] = 'inactive';
 358          }
 359  
 360          $fields = $this->get_fields_for_response( $request );
 361          if ( rest_is_field_included( 'widgets', $fields ) ) {
 362              $sidebars = wp_get_sidebars_widgets();
 363              $widgets  = array_filter(
 364                  isset( $sidebars[ $sidebar['id'] ] ) ? $sidebars[ $sidebar['id'] ] : array(),
 365                  static function ( $widget_id ) use ( $wp_registered_widgets ) {
 366                      return isset( $wp_registered_widgets[ $widget_id ] );
 367                  }
 368              );
 369  
 370              $sidebar['widgets'] = array_values( $widgets );
 371          }
 372  
 373          $schema = $this->get_item_schema();
 374          $data   = array();
 375          foreach ( $schema['properties'] as $property_id => $property ) {
 376              if ( isset( $sidebar[ $property_id ] ) && true === rest_validate_value_from_schema( $sidebar[ $property_id ], $property ) ) {
 377                  $data[ $property_id ] = $sidebar[ $property_id ];
 378              } elseif ( isset( $property['default'] ) ) {
 379                  $data[ $property_id ] = $property['default'];
 380              }
 381          }
 382  
 383          $context = ! empty( $request['context'] ) ? $request['context'] : 'view';
 384          $data    = $this->add_additional_fields_to_object( $data, $request );
 385          $data    = $this->filter_response_by_context( $data, $context );
 386  
 387          $response = rest_ensure_response( $data );
 388  
 389          if ( rest_is_field_included( '_links', $fields ) || rest_is_field_included( '_embedded', $fields ) ) {
 390              $response->add_links( $this->prepare_links( $sidebar ) );
 391          }
 392  
 393          /**
 394           * Filters the REST API response for a sidebar.
 395           *
 396           * @since 5.8.0
 397           *
 398           * @param WP_REST_Response $response    The response object.
 399           * @param array            $raw_sidebar The raw sidebar data.
 400           * @param WP_REST_Request  $request     The request object.
 401           */
 402          return apply_filters( 'rest_prepare_sidebar', $response, $raw_sidebar, $request );
 403      }
 404  
 405      /**
 406       * Prepares links for the sidebar.
 407       *
 408       * @since 5.8.0
 409       *
 410       * @param array $sidebar Sidebar.
 411       * @return array Links for the given widget.
 412       */
 413  	protected function prepare_links( $sidebar ) {
 414          return array(
 415              'collection'               => array(
 416                  'href' => rest_url( sprintf( '%s/%s', $this->namespace, $this->rest_base ) ),
 417              ),
 418              'self'                     => array(
 419                  'href' => rest_url( sprintf( '%s/%s/%s', $this->namespace, $this->rest_base, $sidebar['id'] ) ),
 420              ),
 421              'https://api.w.org/widget' => array(
 422                  'href'       => add_query_arg( 'sidebar', $sidebar['id'], rest_url( '/wp/v2/widgets' ) ),
 423                  'embeddable' => true,
 424              ),
 425          );
 426      }
 427  
 428      /**
 429       * Retrieves the block type' schema, conforming to JSON Schema.
 430       *
 431       * @since 5.8.0
 432       *
 433       * @return array Item schema data.
 434       */
 435  	public function get_item_schema() {
 436          if ( $this->schema ) {
 437              return $this->add_additional_fields_schema( $this->schema );
 438          }
 439  
 440          $schema = array(
 441              '$schema'    => 'http://json-schema.org/draft-04/schema#',
 442              'title'      => 'sidebar',
 443              'type'       => 'object',
 444              'properties' => array(
 445                  'id'            => array(
 446                      'description' => __( 'ID of sidebar.' ),
 447                      'type'        => 'string',
 448                      'context'     => array( 'embed', 'view', 'edit' ),
 449                      'readonly'    => true,
 450                  ),
 451                  'name'          => array(
 452                      'description' => __( 'Unique name identifying the sidebar.' ),
 453                      'type'        => 'string',
 454                      'context'     => array( 'embed', 'view', 'edit' ),
 455                      'readonly'    => true,
 456                  ),
 457                  'description'   => array(
 458                      'description' => __( 'Description of sidebar.' ),
 459                      'type'        => 'string',
 460                      'context'     => array( 'embed', 'view', 'edit' ),
 461                      'readonly'    => true,
 462                  ),
 463                  'class'         => array(
 464                      'description' => __( 'Extra CSS class to assign to the sidebar in the Widgets interface.' ),
 465                      'type'        => 'string',
 466                      'context'     => array( 'embed', 'view', 'edit' ),
 467                      'readonly'    => true,
 468                  ),
 469                  'before_widget' => array(
 470                      'description' => __( 'HTML content to prepend to each widget\'s HTML output when assigned to this sidebar. Default is an opening list item element.' ),
 471                      'type'        => 'string',
 472                      'default'     => '',
 473                      'context'     => array( 'embed', 'view', 'edit' ),
 474                      'readonly'    => true,
 475                  ),
 476                  'after_widget'  => array(
 477                      'description' => __( 'HTML content to append to each widget\'s HTML output when assigned to this sidebar. Default is a closing list item element.' ),
 478                      'type'        => 'string',
 479                      'default'     => '',
 480                      'context'     => array( 'embed', 'view', 'edit' ),
 481                      'readonly'    => true,
 482                  ),
 483                  'before_title'  => array(
 484                      'description' => __( 'HTML content to prepend to the sidebar title when displayed. Default is an opening h2 element.' ),
 485                      'type'        => 'string',
 486                      'default'     => '',
 487                      'context'     => array( 'embed', 'view', 'edit' ),
 488                      'readonly'    => true,
 489                  ),
 490                  'after_title'   => array(
 491                      'description' => __( 'HTML content to append to the sidebar title when displayed. Default is a closing h2 element.' ),
 492                      'type'        => 'string',
 493                      'default'     => '',
 494                      'context'     => array( 'embed', 'view', 'edit' ),
 495                      'readonly'    => true,
 496                  ),
 497                  'status'        => array(
 498                      'description' => __( 'Status of sidebar.' ),
 499                      'type'        => 'string',
 500                      'enum'        => array( 'active', 'inactive' ),
 501                      'context'     => array( 'embed', 'view', 'edit' ),
 502                      'readonly'    => true,
 503                  ),
 504                  'widgets'       => array(
 505                      'description' => __( 'Nested widgets.' ),
 506                      'type'        => 'array',
 507                      'items'       => array(
 508                          'type' => array( 'object', 'string' ),
 509                      ),
 510                      'default'     => array(),
 511                      'context'     => array( 'embed', 'view', 'edit' ),
 512                  ),
 513              ),
 514          );
 515  
 516          $this->schema = $schema;
 517  
 518          return $this->add_additional_fields_schema( $this->schema );
 519      }
 520  }