IntenseWebs/WordPress
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

REST API: Add widget endpoints

Browse Source 
Adds the sidebars, widgets and widget-types REST API endpoints from the
Gutenberg plugin.

Fixes #41683.
Props TimothyBlynJacobs, spacedmonkey, zieladam, jorgefilipecosta, youknowriad, kevin940726.

Built from https://develop.svn.wordpress.org/trunk@50995


git-svn-id: http://core.svn.wordpress.org/trunk@50604 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
noisysocks
2021-05-25 08:27:57 +00:00
parent ed195fbd89
commit 1314542c50
24 changed files with 2151 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

459
wp-includes/rest-api/endpoints/class-wp-rest-sidebars-controller.php Normal file
View File

@@ -0,0 +1,459 @@
<?php
/**
* REST API: WP_REST_Sidebars_Controller class
*
* @package WordPress
* @subpackage REST_API
* @since 5.8.0
*
* Copyright (C) 2015 Martin Pettersson
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
* @author Martin Pettersson <martin_pettersson@outlook.com>
* @copyright 2015 Martin Pettersson
* @license GPLv2
* @link https://github.com/martin-pettersson/wp-rest-api-sidebars
*/
/**
* Core class used to manage a site's sidebars.
*
* @since 5.8.0
*
* @see WP_REST_Controller
*/
class WP_REST_Sidebars_Controller extends WP_REST_Controller {
/**
* Sidebars controller constructor.
*
* @since 5.8.0
*/
public function __construct() {
$this->namespace = 'wp/v2';
$this->rest_base = 'sidebars';
}
/**
* Registers the controllers routes.
*
* @since 5.8.0
*/
public function register_routes() {
register_rest_route(
$this->namespace,
'/' . $this->rest_base,
array(
array(
'methods' => WP_REST_Server::READABLE,
'callback' => array( $this, 'get_items' ),
'permission_callback' => array( $this, 'get_items_permissions_check' ),
'args' => array(
'context' => $this->get_context_param( array( 'default' => 'view' ) ),
),
),
'schema' => array( $this, 'get_public_item_schema' ),
)
);
register_rest_route(
$this->namespace,
'/' . $this->rest_base . '/(?P<id>[\w-]+)',
array(
array(
'methods' => WP_REST_Server::READABLE,
'callback' => array( $this, 'get_item' ),
'permission_callback' => array( $this, 'get_item_permissions_check' ),
'args' => array(
'id' => array(
'description' => __( 'The id of a registered sidebar' ),
'type' => 'string',
),
'context' => $this->get_context_param( array( 'default' => 'view' ) ),
),
),
array(
'methods' => WP_REST_Server::EDITABLE,
'callback' => array( $this, 'update_item' ),
'permission_callback' => array( $this, 'update_item_permissions_check' ),
'args' => $this->get_endpoint_args_for_item_schema( WP_REST_Server::EDITABLE ),
),
'schema' => array( $this, 'get_public_item_schema' ),
)
);
}
/**
* Checks if a given request has access to get sidebars.
*
* @since 5.8.0
*
* @param WP_REST_Request $request Full details about the request.
* @return true|WP_Error True if the request has read access, WP_Error object otherwise.
*/
public function get_items_permissions_check( $request ) {
return $this->do_permissions_check();
}
/**
* Retrieves the list of sidebars (active or inactive).
*
* @since 5.8.0
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
*/
public function get_items( $request ) {
$data = array();
foreach ( (array) wp_get_sidebars_widgets() as $id => $widgets ) {
$sidebar = $this->get_sidebar( $id );
if ( ! $sidebar ) {
continue;
}
$data[] = $this->prepare_response_for_collection(
$this->prepare_item_for_response( $sidebar, $request )
);
}
return rest_ensure_response( $data );
}
/**
* Checks if a given request has access to get a single sidebar.
*
* @since 5.8.0
*
* @param WP_REST_Request $request Full details about the request.
* @return true|WP_Error True if the request has read access, WP_Error object otherwise.
*/
public function get_item_permissions_check( $request ) {
return $this->do_permissions_check();
}
/**
* Retrieves one sidebar from the collection.
*
* @since 5.8.0
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
*/
public function get_item( $request ) {
$sidebar = $this->get_sidebar( $request['id'] );
if ( ! $sidebar ) {
return new WP_Error( 'rest_sidebar_not_found', __( 'No sidebar exists with that id.' ), array( 'status' => 404 ) );
}
return $this->prepare_item_for_response( $sidebar, $request );
}
/**
* Checks if a given request has access to update sidebars.
*
* @since 5.8.0
*
* @param WP_REST_Request $request Full details about the request.
* @return true|WP_Error True if the request has read access, WP_Error object otherwise.
*/
public function update_item_permissions_check( $request ) {
return $this->do_permissions_check();
}
/**
* Updates a sidebar.
*
* @since 5.8.0
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_REST_Response Response object on success, or WP_Error object on failure.
*/
public function update_item( $request ) {
if ( isset( $request['widgets'] ) ) {
$sidebars = wp_get_sidebars_widgets();
foreach ( $sidebars as $sidebar_id => $widgets ) {
foreach ( $widgets as $i => $widget_id ) {
// This automatically removes the passed widget ids from any other sidebars in use.
if ( $sidebar_id !== $request['id'] && in_array( $widget_id, $request['widgets'], true ) ) {
unset( $sidebars[ $sidebar_id ][ $i ] );
}
// This automatically removes omitted widget ids to the inactive sidebar.
if ( $sidebar_id === $request['id'] && ! in_array( $widget_id, $request['widgets'], true ) ) {
$sidebars['wp_inactive_widgets'][] = $widget_id;
}
}
}
$sidebars[ $request['id'] ] = $request['widgets'];
wp_set_sidebars_widgets( $sidebars );
}
$request['context'] = 'edit';
$sidebar = $this->get_sidebar( $request['id'] );
return $this->prepare_item_for_response( $sidebar, $request );
}
/**
* Checks if the user has permissions to make the request.
*
* @since 5.8.0
*
* @return true|WP_Error True if the request has read access, WP_Error object otherwise.
*/
protected function do_permissions_check() {
// Verify if the current user has edit_theme_options capability.
// This capability is required to access the widgets screen.
if ( ! current_user_can( 'edit_theme_options' ) ) {
return new WP_Error(
'rest_cannot_manage_widgets',
__( 'Sorry, you are not allowed to manage widgets on this site.' ),
array( 'status' => rest_authorization_required_code() )
);
}
return true;
}
/**
* Retrieves the registered sidebar with the given id.
*
* @since 5.8.0
*
* @global array $wp_registered_sidebars The registered sidebars.
*
* @param string|int $id ID of the sidebar.
* @return array|null The discovered sidebar, or null if it is not registered.
*/
protected function get_sidebar( $id ) {
global $wp_registered_sidebars;
foreach ( (array) $wp_registered_sidebars as $sidebar ) {
if ( $sidebar['id'] === $id ) {
return $sidebar;
}
}
if ( 'wp_inactive_widgets' === $id ) {
return array(
'id' => 'wp_inactive_widgets',
'name' => __( 'Inactive widgets' ),
);
}
return null;
}
/**
* Prepares a single sidebar output for response.
*
* @since 5.8.0
*
* @global array $wp_registered_sidebars The registered sidebars.
* @global array $wp_registered_widgets The registered widgets.
*
* @param array $raw_sidebar Sidebar instance.
* @param WP_REST_Request $request Full details about the request.
*
* @return WP_REST_Response Prepared response object.
*/
public function prepare_item_for_response( $raw_sidebar, $request ) {
global $wp_registered_sidebars, $wp_registered_widgets;
$id = $raw_sidebar['id'];
$sidebar = array( 'id' => $id );
if ( isset( $wp_registered_sidebars[ $id ] ) ) {
$registered_sidebar = $wp_registered_sidebars[ $id ];
$sidebar['status'] = 'active';
$sidebar['name'] = isset( $registered_sidebar['name'] ) ? $registered_sidebar['name'] : '';
$sidebar['description'] = isset( $registered_sidebar['description'] ) ? $registered_sidebar['description'] : '';
$sidebar['class'] = isset( $registered_sidebar['class'] ) ? $registered_sidebar['class'] : '';
$sidebar['before_widget'] = isset( $registered_sidebar['before_widget'] ) ? $registered_sidebar['before_widget'] : '';
$sidebar['after_widget'] = isset( $registered_sidebar['after_widget'] ) ? $registered_sidebar['after_widget'] : '';
$sidebar['before_title'] = isset( $registered_sidebar['before_title'] ) ? $registered_sidebar['before_title'] : '';
$sidebar['after_title'] = isset( $registered_sidebar['after_title'] ) ? $registered_sidebar['after_title'] : '';
} else {
$sidebar['status'] = 'inactive';
$sidebar['name'] = $raw_sidebar['name'];
$sidebar['description'] = '';
$sidebar['class'] = '';
}
$fields = $this->get_fields_for_response( $request );
if ( rest_is_field_included( 'widgets', $fields ) ) {
$sidebars = wp_get_sidebars_widgets();
$widgets = array_filter(
isset( $sidebars[ $sidebar['id'] ] ) ? $sidebars[ $sidebar['id'] ] : array(),
static function ( $widget_id ) use ( $wp_registered_widgets ) {
return isset( $wp_registered_widgets[ $widget_id ] );
}
);
$sidebar['widgets'] = $widgets;
}
$schema = $this->get_item_schema();
$data = array();
foreach ( $schema['properties'] as $property_id => $property ) {
if ( isset( $sidebar[ $property_id ] ) && true === rest_validate_value_from_schema( $sidebar[ $property_id ], $property ) ) {
$data[ $property_id ] = $sidebar[ $property_id ];
} elseif ( isset( $property['default'] ) ) {
$data[ $property_id ] = $property['default'];
}
}
$context = ! empty( $request['context'] ) ? $request['context'] : 'view';
$data = $this->add_additional_fields_to_object( $data, $request );
$data = $this->filter_response_by_context( $data, $context );
$response = rest_ensure_response( $data );
$response->add_links( $this->prepare_links( $sidebar ) );
/**
* Filters the REST API response for a sidebar.
*
* @since 5.8.0
*
* @param WP_REST_Response $response The response object.
* @param array $raw_sidebar The raw sidebar data.
* @param WP_REST_Request $request The request object.
*/
return apply_filters( 'rest_prepare_sidebar', $response, $raw_sidebar, $request );
}
/**
* Prepares links for the sidebar.
*
* @since 5.8.0
*
* @param array $sidebar Sidebar.
*
* @return array Links for the given widget.
*/
protected function prepare_links( $sidebar ) {
return array(
'collection' => array(
'href' => rest_url( sprintf( '%s/%s', $this->namespace, $this->rest_base ) ),
),
'self' => array(
'href' => rest_url( sprintf( '%s/%s/%s', $this->namespace, $this->rest_base, $sidebar['id'] ) ),
),
'https://api.w.org/widget' => array(
'href' => add_query_arg( 'sidebar', $sidebar['id'], rest_url( '/wp/v2/widgets' ) ),
'embeddable' => true,
),
);
}
/**
* Retrieves the block type' schema, conforming to JSON Schema.
*
* @return array Item schema data.
*/
public function get_item_schema() {
if ( $this->schema ) {
return $this->add_additional_fields_schema( $this->schema );
}
$schema = array(
'$schema' => 'http://json-schema.org/draft-04/schema#',
'title' => 'sidebar',
'type' => 'object',
'properties' => array(
'id' => array(
'description' => __( 'ID of sidebar.' ),
'type' => 'string',
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'name' => array(
'description' => __( 'Unique name identifying the sidebar.' ),
'type' => 'string',
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'description' => array(
'description' => __( 'Description of sidebar.' ),
'type' => 'string',
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'class' => array(
'description' => __( 'Extra CSS class to assign to the sidebar in the Widgets interface.' ),
'type' => 'string',
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'before_widget' => array(
'description' => __( 'HTML content to prepend to each widget\'s HTML output when assigned to this sidebar. Default is an opening list item element.' ),
'type' => 'string',
'default' => '',
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'after_widget' => array(
'description' => __( 'HTML content to append to each widget\'s HTML output when assigned to this sidebar. Default is a closing list item element.' ),
'type' => 'string',
'default' => '',
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'before_title' => array(
'description' => __( 'HTML content to prepend to the sidebar title when displayed. Default is an opening h2 element.' ),
'type' => 'string',
'default' => '',
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'after_title' => array(
'description' => __( 'HTML content to append to the sidebar title when displayed. Default is a closing h2 element.' ),
'type' => 'string',
'default' => '',
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'status' => array(
'description' => __( 'Status of sidebar.' ),
'type' => 'string',
'enum' => array( 'active', 'inactive' ),
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'widgets' => array(
'description' => __( 'Nested widgets.' ),
'type' => 'array',
'items' => array(
'type' => array( 'object', 'string' ),
),
'default' => array(),
'context' => array( 'embed', 'view', 'edit' ),
),
),
);
$this->schema = $schema;
return $this->add_additional_fields_schema( $this->schema );
}
}

551
wp-includes/rest-api/endpoints/class-wp-rest-widget-types-controller.php Normal file
View File

@@ -0,0 +1,551 @@
<?php
/**
* REST API: WP_REST_Widget_Types_Controller class
*
* @package WordPress
* @subpackage REST_API
* @since 5.8.0
*/
/**
* Core class to access widget types via the REST API.
*
* @since 5.8.0
*
* @see WP_REST_Controller
*/
class WP_REST_Widget_Types_Controller extends WP_REST_Controller {
/**
* Constructor.
*
* @since 5.8.0
*/
public function __construct() {
$this->namespace = 'wp/v2';
$this->rest_base = 'widget-types';
}
/**
* Registers the widget type routes.
*
* @since 5.8.0
*
* @see register_rest_route()
*/
public function register_routes() {
register_rest_route(
$this->namespace,
'/' . $this->rest_base,
array(
array(
'methods' => WP_REST_Server::READABLE,
'callback' => array( $this, 'get_items' ),
'permission_callback' => array( $this, 'get_items_permissions_check' ),
'args' => $this->get_collection_params(),
),
'schema' => array( $this, 'get_public_item_schema' ),
)
);
register_rest_route(
$this->namespace,
'/' . $this->rest_base . '/(?P<id>[a-zA-Z0-9_-]+)',
array(
'args' => array(
'id' => array(
'description' => __( 'The widget type id.' ),
'type' => 'string',
),
),
array(
'methods' => WP_REST_Server::READABLE,
'callback' => array( $this, 'get_item' ),
'permission_callback' => array( $this, 'get_item_permissions_check' ),
'args' => $this->get_collection_params(),
),
'schema' => array( $this, 'get_public_item_schema' ),
)
);
register_rest_route(
$this->namespace,
'/' . $this->rest_base . '/(?P<id>[a-zA-Z0-9_-]+)/encode',
array(
'args' => array(
'id' => array(
'description' => __( 'The widget type id.' ),
'type' => 'string',
'required' => true,
),
'instance' => array(
'description' => __( 'Current instance settings of the widget.' ),
'type' => 'object',
),
'form_data' => array(
'description' => __( 'Serialized widget form data to encode into instance settings.' ),
'type' => 'string',
'sanitize_callback' => function( $string ) {
$array = array();
wp_parse_str( $string, $array );
return $array;
},
),
),
array(
'methods' => WP_REST_Server::CREATABLE,
'permission_callback' => array( $this, 'get_item_permissions_check' ),
'callback' => array( $this, 'encode_form_data' ),
),
)
);
}
/**
* Checks whether a given request has permission to read widget types.
*
* @since 5.8.0
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_Error|bool True if the request has read access, WP_Error object otherwise.
*/
public function get_items_permissions_check( $request ) {
return $this->check_read_permission();
}
/**
* Retrieves the list of all widget types.
*
* @since 5.8.0
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_Error|WP_REST_Response Response object on success, or WP_Error object on failure.
*/
public function get_items( $request ) {
$data = array();
foreach ( $this->get_widgets() as $widget ) {
$widget_type = $this->prepare_item_for_response( $widget, $request );
$data[] = $this->prepare_response_for_collection( $widget_type );
}
return rest_ensure_response( $data );
}
/**
* Checks if a given request has access to read a widget type.
*
* @since 5.8.0
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_Error|bool True if the request has read access for the item, WP_Error object otherwise.
*/
public function get_item_permissions_check( $request ) {
$check = $this->check_read_permission();
if ( is_wp_error( $check ) ) {
return $check;
}
$widget_id = $request['id'];
$widget_type = $this->get_widget( $widget_id );
if ( is_wp_error( $widget_type ) ) {
return $widget_type;
}
return true;
}
/**
* Checks whether the user can read widget types.
*
* @since 5.8.0
*
* @return WP_Error|bool True if the widget type is visible, WP_Error otherwise.
*/
protected function check_read_permission() {
if ( ! current_user_can( 'edit_theme_options' ) ) {
return new WP_Error(
'rest_cannot_manage_widgets',
__( 'Sorry, you are not allowed to manage widgets on this site.' ),
array(
'status' => rest_authorization_required_code(),
)
);
}
return true;
}
/**
* Gets the details about the requested widget.
*
* @since 5.8.0
*
* @param string $id The widget type id.
* @return array|WP_Error The array of widget data if the name is valid, WP_Error otherwise.
*/
public function get_widget( $id ) {
foreach ( $this->get_widgets() as $widget ) {
if ( $id === $widget['id'] ) {
return $widget;
}
}
return new WP_Error( 'rest_widget_type_invalid', __( 'Invalid widget type.' ), array( 'status' => 404 ) );
}
/**
* Normalize array of widgets.
*
* @since 5.8.0
*
* @global array $wp_registered_widgets The list of registered widgets.
*
* @return array Array of widgets.
*/
protected function get_widgets() {
global $wp_widget_factory, $wp_registered_widgets;
$widgets = array();
foreach ( $wp_registered_widgets as $widget ) {
$parsed_id = wp_parse_widget_id( $widget['id'] );
$widget_object = $wp_widget_factory->get_widget_object( $parsed_id['id_base'] );
$widget['id'] = $parsed_id['id_base'];
$widget['is_multi'] = (bool) $widget_object;
unset( $widget['callback'] );
$classname = '';
foreach ( (array) $widget['classname'] as $cn ) {
if ( is_string( $cn ) ) {
$classname .= '_' . $cn;
} elseif ( is_object( $cn ) ) {
$classname .= '_' . get_class( $cn );
}
}
$widget['classname'] = ltrim( $classname, '_' );
$widgets[] = $widget;
}
return $widgets;
}
/**
* Retrieves a single widget type from the collection.
*
* @since 5.8.0
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_Error|WP_REST_Response Response object on success, or WP_Error object on failure.
*/
public function get_item( $request ) {
$widget_id = $request['id'];
$widget_type = $this->get_widget( $widget_id );
if ( is_wp_error( $widget_type ) ) {
return $widget_type;
}
$data = $this->prepare_item_for_response( $widget_type, $request );
return rest_ensure_response( $data );
}
/**
* Prepares a widget type object for serialization.
*
* @since 5.8.0
*
* @param array $widget_type Widget type data.
* @param WP_REST_Request $request Full details about the request.
* @return WP_REST_Response Widget type data.
*/
public function prepare_item_for_response( $widget_type, $request ) {
$fields = $this->get_fields_for_response( $request );
$data = array(
'id' => $widget_type['id'],
);
$schema = $this->get_item_schema();
$extra_fields = array(
'name',
'description',
'is_multi',
'classname',
'widget_class',
'option_name',
'customize_selective_refresh',
);
foreach ( $extra_fields as $extra_field ) {
if ( ! rest_is_field_included( $extra_field, $fields ) ) {
continue;
}
if ( isset( $widget_type[ $extra_field ] ) ) {
$field = $widget_type[ $extra_field ];
} elseif ( array_key_exists( 'default', $schema['properties'][ $extra_field ] ) ) {
$field = $schema['properties'][ $extra_field ]['default'];
} else {
$field = '';
}
$data[ $extra_field ] = rest_sanitize_value_from_schema( $field, $schema['properties'][ $extra_field ] );
}
$context = ! empty( $request['context'] ) ? $request['context'] : 'view';
$data = $this->add_additional_fields_to_object( $data, $request );
$data = $this->filter_response_by_context( $data, $context );
$response = rest_ensure_response( $data );
$response->add_links( $this->prepare_links( $widget_type ) );
/**
* Filters the REST API response for a widget type.
*
* @since 5.8.0
*
* @param WP_REST_Response $response The response object.
* @param array $widget_type The array of widget data.
* @param WP_REST_Request $request The request object.
*/
return apply_filters( 'rest_prepare_widget_type', $response, $widget_type, $request );
}
/**
* Prepares links for the widget type.
*
* @since 5.8.0
*
* @param array $widget_type Widget type data.
* @return array Links for the given widget type.
*/
protected function prepare_links( $widget_type ) {
return array(
'collection' => array(
'href' => rest_url( sprintf( '%s/%s', $this->namespace, $this->rest_base ) ),
),
'self' => array(
'href' => rest_url( sprintf( '%s/%s/%s', $this->namespace, $this->rest_base, $widget_type['id'] ) ),
),
);
}
/**
* Retrieves the widget type's schema, conforming to JSON Schema.
*
* @since 5.8.0
*
* @return array Item schema data.
*/
public function get_item_schema() {
if ( $this->schema ) {
return $this->add_additional_fields_schema( $this->schema );
}
$schema = array(
'$schema' => 'http://json-schema.org/draft-04/schema#',
'title' => 'widget-type',
'type' => 'object',
'properties' => array(
'id' => array(
'description' => __( 'Unique slug identifying the widget type.' ),
'type' => 'string',
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'name' => array(
'description' => __( 'Human-readable name identifying the widget type.' ),
'type' => 'string',
'default' => '',
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
'description' => array(
'description' => __( 'Description of the widget.' ),
'type' => 'string',
'default' => '',
'context' => array( 'view', 'edit', 'embed' ),
),
'is_multi' => array(
'description' => __( 'Whether the widget supports multiple instances' ),
'type' => 'boolean',
'context' => array( 'view', 'edit', 'embed' ),
'readonly' => true,
),
'classname' => array(
'description' => __( 'Class name' ),
'type' => 'string',
'default' => '',
'context' => array( 'embed', 'view', 'edit' ),
'readonly' => true,
),
),
);
$this->schema = $schema;
return $this->add_additional_fields_schema( $this->schema );
}
/**
* An RPC-style endpoint which can be used by clients to turn user input in
* a widget admin form into an encoded instance object.
*
* Accepts:
*
* - id: A widget type ID.
* - instance: A widget's encoded instance object. Optional.
* - form_data: Form data from submitting a widget's admin form. Optional.
*
* Returns:
* - instance: The encoded instance object after updating the widget with
* the given form data.
* - form: The widget's admin form after updating the widget with the
* given form data.
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
*/
public function encode_form_data( $request ) {
global $wp_widget_factory;
$id = $request['id'];
$widget_object = $wp_widget_factory->get_widget_object( $id );
if ( ! $widget_object ) {
return new WP_Error(
'rest_invalid_widget',
__( 'Cannot preview a widget that does not extend WP_Widget.' ),
array( 'status' => 400 )
);
}
// Set the widget's number so that the id attributes in the HTML that we
// return are predictable.
if ( isset( $request['number'] ) && is_numeric( $request['number'] ) ) {
$widget_object->_set( (int) $request['number'] );
} else {
$widget_object->_set( -1 );
}
if ( isset( $request['instance']['encoded'], $request['instance']['hash'] ) ) {
$serialized_instance = base64_decode( $request['instance']['encoded'] );
if ( ! hash_equals( wp_hash( $serialized_instance ), $request['instance']['hash'] ) ) {
return new WP_Error(
'rest_invalid_widget',
__( 'The provided instance is malformed.' ),
array( 'status' => 400 )
);
}
$instance = unserialize( $serialized_instance );
} else {
$instance = array();
}
if (
isset( $request['form_data'][ "widget-$id" ] ) &&
is_array( $request['form_data'][ "widget-$id" ] )
) {
$new_instance = array_values( $request['form_data'][ "widget-$id" ] )[0];
$old_instance = $instance;
$instance = $widget_object->update( $new_instance, $old_instance );
/** This filter is documented in wp-includes/class-wp-widget.php */
$instance = apply_filters(
'widget_update_callback',
$instance,
$new_instance,
$old_instance,
$widget_object
);
}
$serialized_instance = serialize( $instance );
$response = array(
'form' => trim(
$this->get_widget_form(
$widget_object,
$instance
)
),
'preview' => trim(
$this->get_widget_preview(
$widget_object,
$instance
)
),
'instance' => array(
'encoded' => base64_encode( $serialized_instance ),
'hash' => wp_hash( $serialized_instance ),
),
);
if ( ! empty( $widget_object->widget_options['show_instance_in_rest'] ) ) {
// Use new stdClass so that JSON result is {} and not [].
$response['instance']['raw'] = empty( $instance ) ? new stdClass : $instance;
}
return rest_ensure_response( $response );
}
/**
* Returns the output of WP_Widget::widget() when called with the provided
* instance. Used by encode_form_data() to preview a widget.
* @param WP_Widget $widget_object Widget object to call widget() on.
* @param array $instance Widget instance settings.
* @return string
*/
private function get_widget_preview( $widget_object, $instance ) {
ob_start();
the_widget( get_class( $widget_object ), $instance );
return ob_get_clean();
}
/**
* Returns the output of WP_Widget::form() when called with the provided
* instance. Used by encode_form_data() to preview a widget's form.
*
* @param WP_Widget $widget_object Widget object to call widget() on.
* @param array $instance Widget instance settings.
* @return string
*/
private function get_widget_form( $widget_object, $instance ) {
ob_start();
/** This filter is documented in wp-includes/class-wp-widget.php */
$instance = apply_filters(
'widget_form_callback',
$instance,
$widget_object
);
if ( false !== $instance ) {
$return = $widget_object->form( $instance );
/** This filter is documented in wp-includes/class-wp-widget.php */
do_action_ref_array(
'in_widget_form',
array( &$widget_object, &$return, $instance )
);
}
return ob_get_clean();
}
/**
* Retrieves the query params for collections.
*
* @since 5.8.0
*
* @return array Collection parameters.
*/
public function get_collection_params() {
return array(
'context' => $this->get_context_param( array( 'default' => 'view' ) ),
);
}
}

693
wp-includes/rest-api/endpoints/class-wp-rest-widgets-controller.php Normal file
View File

@@ -0,0 +1,693 @@
<?php
/**
* REST API: WP_REST_Widgets_Controller class
*
* @package WordPress
* @subpackage REST_API
* @since 5.8.0
*/
/**
* Core class to access widgets via the REST API.
*
* @since 5.8.0
*
* @see WP_REST_Controller
*/
class WP_REST_Widgets_Controller extends WP_REST_Controller {
/**
* Widgets controller constructor.
*
* @since 5.8.0
*/
public function __construct() {
$this->namespace = 'wp/v2';
$this->rest_base = 'widgets';
}
/**
* Registers the widget routes for the controller.
*
* @since 5.8.0
*/
public function register_routes() {
register_rest_route(
$this->namespace,
$this->rest_base,
array(
array(
'methods' => WP_REST_Server::READABLE,
'callback' => array( $this, 'get_items' ),
'permission_callback' => array( $this, 'get_items_permissions_check' ),
'args' => $this->get_collection_params(),
),
array(
'methods' => WP_REST_Server::CREATABLE,
'callback' => array( $this, 'create_item' ),
'permission_callback' => array( $this, 'create_item_permissions_check' ),
'args' => $this->get_endpoint_args_for_item_schema(),
),
'allow_batch' => array( 'v1' => true ),
'schema' => array( $this, 'get_public_item_schema' ),
)
);
register_rest_route(
$this->namespace,
$this->rest_base . '/(?P<id>[\w\-]+)',
array(
array(
'methods' => WP_REST_Server::READABLE,
'callback' => array( $this, 'get_item' ),
'permission_callback' => array( $this, 'get_item_permissions_check' ),
'args' => array(
'context' => $this->get_context_param( array( 'default' => 'view' ) ),
),
),
array(
'methods' => WP_REST_Server::EDITABLE,
'callback' => array( $this, 'update_item' ),
'permission_callback' => array( $this, 'update_item_permissions_check' ),
'args' => $this->get_endpoint_args_for_item_schema( WP_REST_Server::EDITABLE ),
),
array(
'methods' => WP_REST_Server::DELETABLE,
'callback' => array( $this, 'delete_item' ),
'permission_callback' => array( $this, 'delete_item_permissions_check' ),
'args' => array(
'force' => array(
'description' => __( 'Whether to force removal of the widget, or move it to the inactive sidebar.' ),
'type' => 'boolean',
),
),
),
'allow_batch' => array( 'v1' => true ),
'schema' => array( $this, 'get_public_item_schema' ),
)
);
}
/**
* Checks if a given request has access to get widgets.
*
* @since 5.8.0
*
* @param WP_REST_Request $request Full details about the request.
* @return true|WP_Error True if the request has read access, WP_Error object otherwise.
*/
public function get_items_permissions_check( $request ) {
return $this->permissions_check();
}
/**
* Retrieves a collection of widgets.
*
* @since 5.8.0
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
*/
public function get_items( $request ) {
$prepared = array();
foreach ( wp_get_sidebars_widgets() as $sidebar_id => $widget_ids ) {
if ( isset( $request['sidebar'] ) && $sidebar_id !== $request['sidebar'] ) {
continue;
}
foreach ( $widget_ids as $widget_id ) {
$response = $this->prepare_item_for_response( compact( 'sidebar_id', 'widget_id' ), $request );
if ( ! is_wp_error( $response ) ) {
$prepared[] = $this->prepare_response_for_collection( $response );
}
}
}
return new WP_REST_Response( $prepared );
}
/**
* Checks if a given request has access to get a widget.
*
* @since 5.8.0
*
* @param WP_REST_Request $request Full details about the request.
* @return true|WP_Error True if the request has read access, WP_Error object otherwise.
*/
public function get_item_permissions_check( $request ) {
return $this->permissions_check();
}
/**
* Gets an individual widget.
*
* @since 5.8.0
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
*/
public function get_item( $request ) {
$widget_id = $request['id'];
$sidebar_id = wp_find_widgets_sidebar( $widget_id );
if ( is_null( $sidebar_id ) ) {
return new WP_Error(
'rest_widget_not_found',
__( 'No widget was found with that id.' ),
array( 'status' => 404 )
);
}
return $this->prepare_item_for_response( compact( 'widget_id', 'sidebar_id' ), $request );
}
/**
* Checks if a given request has access to create widgets.
*
* @since 5.8.0
*
* @param WP_REST_Request $request Full details about the request.
* @return true|WP_Error True if the request has read access, WP_Error object otherwise.
*/
public function create_item_permissions_check( $request ) {
return $this->permissions_check();
}
/**
* Creates a widget.
*
* @since 5.8.0
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
*/
public function create_item( $request ) {
$sidebar_id = $request['sidebar'];
$widget_id = $this->save_widget( $request );
if ( is_wp_error( $widget_id ) ) {
return $widget_id;
}
wp_assign_widget_to_sidebar( $widget_id, $sidebar_id );
$request['context'] = 'edit';
$response = $this->prepare_item_for_response( compact( 'sidebar_id', 'widget_id' ), $request );
if ( is_wp_error( $response ) ) {
return $response;
}
$response->set_status( 201 );
return $response;
}
/**
* Checks if a given request has access to update widgets.
*
* @since 5.8.0
*
* @param WP_REST_Request $request Full details about the request.
* @return true|WP_Error True if the request has read access, WP_Error object otherwise.
*/
public function update_item_permissions_check( $request ) {
return $this->permissions_check();
}
/**
* Updates an existing widget.
*
* @since 5.8.0
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
*/
public function update_item( $request ) {
global $wp_widget_factory;
$widget_id = $request['id'];
$sidebar_id = wp_find_widgets_sidebar( $widget_id );
// Allow sidebar to be unset or missing when widget is not a WP_Widget.
$parsed_id = wp_parse_widget_id( $widget_id );
$widget_object = $wp_widget_factory->get_widget_object( $parsed_id['id_base'] );
if ( is_null( $sidebar_id ) && $widget_object ) {
return new WP_Error(
'rest_widget_not_found',
__( 'No widget was found with that id.' ),
array( 'status' => 404 )
);
}
if (
$request->has_param( 'instance' ) ||
$request->has_param( 'form_data' )
) {
$maybe_error = $this->save_widget( $request );
if ( is_wp_error( $maybe_error ) ) {
return $maybe_error;
}
}
if ( $request->has_param( 'sidebar' ) ) {
if ( $sidebar_id !== $request['sidebar'] ) {
$sidebar_id = $request['sidebar'];
wp_assign_widget_to_sidebar( $widget_id, $sidebar_id );
}
}
$request['context'] = 'edit';
return $this->prepare_item_for_response( compact( 'widget_id', 'sidebar_id' ), $request );
}
/**
* Checks if a given request has access to delete widgets.
*
* @since 5.8.0
*
* @param WP_REST_Request $request Full details about the request.
* @return true|WP_Error True if the request has read access, WP_Error object otherwise.
*/
public function delete_item_permissions_check( $request ) {
return $this->permissions_check();
}
/**
* Deletes a widget.
*
* @since 5.8.0
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
*/
public function delete_item( $request ) {
$widget_id = $request['id'];
$sidebar_id = wp_find_widgets_sidebar( $widget_id );
if ( is_null( $sidebar_id ) ) {
return new WP_Error(
'rest_widget_not_found',
__( 'No widget was found with that id.' ),
array( 'status' => 404 )
);
}
$request['context'] = 'edit';
if ( $request['force'] ) {
$prepared = $this->prepare_item_for_response( compact( 'widget_id', 'sidebar_id' ), $request );
wp_assign_widget_to_sidebar( $widget_id, '' );
$prepared->set_data(
array(
'deleted' => true,
'previous' => $prepared->get_data(),
)
);
} else {
wp_assign_widget_to_sidebar( $widget_id, 'wp_inactive_widgets' );
$prepared = $this->prepare_item_for_response(
array(
'sidebar_id' => 'wp_inactive_widgets',
'widget_id' => $widget_id,
),
$request
);
}
return $prepared;
}
/**
* Performs a permissions check for managing widgets.
*
* @since 5.8.0
*
* @return true|WP_Error
*/
protected function permissions_check() {
if ( ! current_user_can( 'edit_theme_options' ) ) {
return new WP_Error(
'rest_cannot_manage_widgets',
__( 'Sorry, you are not allowed to manage widgets on this site.' ),
array(
'status' => rest_authorization_required_code(),
)
);
}
return true;
}
/**
* Saves the widget in the request object.
*
* @since 5.8.0
*
* @param WP_REST_Request $request Full details about the request.
*
* @return string|WP_Error The saved widget ID.
*/
protected function save_widget( $request ) {
global $wp_widget_factory, $wp_registered_widget_updates;
require_once ABSPATH . 'wp-admin/includes/widgets.php'; // For next_widget_id_number().
if ( isset( $request['id'] ) ) {
// Saving an existing widget.
$id = $request['id'];
$parsed_id = wp_parse_widget_id( $id );
$id_base = $parsed_id['id_base'];
$number = isset( $parsed_id['number'] ) ? $parsed_id['number'] : null;
$widget_object = $wp_widget_factory->get_widget_object( $id_base );
} elseif ( $request['id_base'] ) {
// Saving a new widget.
$id_base = $request['id_base'];
$widget_object = $wp_widget_factory->get_widget_object( $id_base );
$number = $widget_object ? next_widget_id_number( $id_base ) : null;
$id = $widget_object ? $id_base . '-' . $number : $id_base;
} else {
return new WP_Error(
'rest_invalid_widget',
__( 'Widget type (id_base) is required.' ),
array( 'status' => 400 )
);
}
if ( ! isset( $wp_registered_widget_updates[ $id_base ] ) ) {
return new WP_Error(
'rest_invalid_widget',
__( 'The provided widget type (id_base) cannot be updated.' ),
array( 'status' => 400 )
);
}
if ( isset( $request['instance'] ) ) {
if ( ! $widget_object ) {
return new WP_Error(
'rest_invalid_widget',
__( 'Cannot set instance on a widget that does not extend WP_Widget.' ),
array( 'status' => 400 )
);
}
if ( isset( $request['instance']['raw'] ) ) {
if ( empty( $widget_object->widget_options['show_instance_in_rest'] ) ) {
return new WP_Error(
'rest_invalid_widget',
__( 'Widget type does not support raw instances.' ),
array( 'status' => 400 )
);
}
$instance = $request['instance']['raw'];
} elseif ( isset( $request['instance']['encoded'], $request['instance']['hash'] ) ) {
$serialized_instance = base64_decode( $request['instance']['encoded'] );
if ( ! hash_equals( wp_hash( $serialized_instance ), $request['instance']['hash'] ) ) {
return new WP_Error(
'rest_invalid_widget',
__( 'The provided instance is malformed.' ),
array( 'status' => 400 )
);
}
$instance = unserialize( $serialized_instance );
} else {
return new WP_Error(
'rest_invalid_widget',
__( 'The provided instance is invalid. Must contain raw OR encoded and hash.' ),
array( 'status' => 400 )
);
}
$form_data = array(
"widget-$id_base" => array(
$number => $instance,
),
);
} elseif ( isset( $request['form_data'] ) ) {
$form_data = $request['form_data'];
} else {
$form_data = array();
}
$original_post = $_POST;
$original_request = $_REQUEST;
foreach ( $form_data as $key => $value ) {
$slashed_value = wp_slash( $value );
$_POST[ $key ] = $slashed_value;
$_REQUEST[ $key ] = $slashed_value;
}
$callback = $wp_registered_widget_updates[ $id_base ]['callback'];
$params = $wp_registered_widget_updates[ $id_base ]['params'];
if ( is_callable( $callback ) ) {
ob_start();
call_user_func_array( $callback, $params );
ob_end_clean();
}
$_POST = $original_post;
$_REQUEST = $original_request;
if ( $widget_object ) {
// Register any multi-widget that the update callback just created.
$widget_object->_set( $number );
$widget_object->_register_one( $number );
// WP_Widget sets updated = true after an update to prevent more
// than one widget from being saved per request. This isn't what we
// want in the REST API, though, as we support batch requests.
$widget_object->updated = false;
}
return $id;
}
/**
* Prepares the widget for the REST response.
*
* @since 5.8.0
*
* @global array $wp_registered_sidebars The registered sidebars.
* @global array $wp_registered_widgets The registered widgets.
* @global array $wp_registered_widget_controls The registered widget controls.
*
* @param array $item An array containing a widget_id and sidebar_id.
* @param WP_REST_Request $request Request object.
* @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
*/
public function prepare_item_for_response( $item, $request ) {
global $wp_widget_factory, $wp_registered_widgets;
$widget_id = $item['widget_id'];
$sidebar_id = $item['sidebar_id'];
if ( ! isset( $wp_registered_widgets[ $widget_id ] ) ) {
return new WP_Error(
'rest_invalid_widget',
__( 'The requested widget is invalid.' ),
array( 'status' => 500 )
);
}
$widget = $wp_registered_widgets[ $widget_id ];
$parsed_id = wp_parse_widget_id( $widget_id );
$fields = $this->get_fields_for_response( $request );
$prepared = array(
'id' => $widget_id,
'id_base' => $parsed_id['id_base'],
'sidebar' => $sidebar_id,
'rendered' => '',
'rendered_form' => null,
'instance' => null,
);
if (
rest_is_field_included( 'rendered', $fields ) &&
'wp_inactive_widgets' !== $sidebar_id
) {
$prepared['rendered'] = trim( wp_render_widget( $widget_id, $sidebar_id ) );
}
if ( rest_is_field_included( 'rendered_form', $fields ) ) {
$rendered_form = wp_render_widget_control( $widget_id );
if ( ! is_null( $rendered_form ) ) {
$prepared['rendered_form'] = trim( $rendered_form );
}
}
if ( rest_is_field_included( 'instance', $fields ) ) {
$widget_object = $wp_widget_factory->get_widget_object( $parsed_id['id_base'] );
if ( $widget_object && isset( $parsed_id['number'] ) ) {
$all_instances = $widget_object->get_settings();
$instance = $all_instances[ $parsed_id['number'] ];
$serialized_instance = serialize( $instance );
$prepared['instance']['encoded'] = base64_encode( $serialized_instance );
$prepared['instance']['hash'] = wp_hash( $serialized_instance );
if ( ! empty( $widget_object->widget_options['show_instance_in_rest'] ) ) {
// Use new stdClass so that JSON result is {} and not [].
$prepared['instance']['raw'] = empty( $instance ) ? new stdClass : $instance;
}
}
}
$context = ! empty( $request['context'] ) ? $request['context'] : 'view';
$prepared = $this->add_additional_fields_to_object( $prepared, $request );
$prepared = $this->filter_response_by_context( $prepared, $context );
$response = rest_ensure_response( $prepared );
$response->add_links( $this->prepare_links( $prepared ) );
/**
* Filters the REST API response for a widget.
*
* @since 5.8.0
*
* @param WP_REST_Response $response The response object.
* @param array $widget The registered widget data.
* @param WP_REST_Request $request Request used to generate the response.
*/
return apply_filters( 'rest_prepare_widget', $response, $widget, $request );
}
/**
* Prepares links for the widget.
*
* @since 5.8.0
*
* @param array $prepared Widget.
* @return array Links for the given widget.
*/
protected function prepare_links( $prepared ) {
$id_base = ! empty( $prepared['id_base'] ) ? $prepared['id_base'] : $prepared['id'];
return array(
'self' => array(
'href' => rest_url( sprintf( '%s/%s/%s', $this->namespace, $this->rest_base, $prepared['id'] ) ),
),
'collection' => array(
'href' => rest_url( sprintf( '%s/%s', $this->namespace, $this->rest_base ) ),
),
'about' => array(
'href' => rest_url( sprintf( 'wp/v2/widget-types/%s', $id_base ) ),
'embeddable' => true,
),
'https://api.w.org/sidebar' => array(
'href' => rest_url( sprintf( 'wp/v2/sidebars/%s/', $prepared['sidebar'] ) ),
),
);
}
/**
* Gets the list of collection params.
*
* @since 5.8.0
*
* @return array[]
*/
public function get_collection_params() {
return array(
'context' => $this->get_context_param( array( 'default' => 'view' ) ),
'sidebar' => array(
'description' => __( 'The sidebar to return widgets for.' ),
'type' => 'string',
),
);
}
/**
* Retrieves the widget's schema, conforming to JSON Schema.
*
* @since 5.8.0
*
* @return array Item schema data.
*/
public function get_item_schema() {
if ( $this->schema ) {
return $this->add_additional_fields_schema( $this->schema );
}
$this->schema = array(
'$schema' => 'http://json-schema.org/draft-04/schema#',
'title' => 'widget',
'type' => 'object',
'properties' => array(
'id' => array(
'description' => __( 'Unique identifier for the widget.' ),
'type' => 'string',
'context' => array( 'view', 'edit', 'embed' ),
),
'id_base' => array(
'description' => __( 'The type of the widget. Corresponds to ID in widget-types endpoint.' ),
'type' => 'string',
'context' => array( 'view', 'edit', 'embed' ),
),
'sidebar' => array(
'description' => __( 'The sidebar the widget belongs to.' ),
'type' => 'string',
'default' => 'wp_inactive_widgets',
'required' => true,
'context' => array( 'view', 'edit', 'embed' ),
),
'rendered' => array(
'description' => __( 'HTML representation of the widget.' ),
'type' => 'string',
'context' => array( 'view', 'edit', 'embed' ),
'readonly' => true,
),
'rendered_form' => array(
'description' => __( 'HTML representation of the widget admin form.' ),
'type' => 'string',
'context' => array( 'edit' ),
'readonly' => true,
),
'instance' => array(
'description' => __( 'Instance settings of the widget, if supported.' ),
'type' => 'object',
'context' => array( 'view', 'edit', 'embed' ),
'default' => null,
'properties' => array(
'encoded' => array(
'description' => __( 'Base64 encoded representation of the instance settings.' ),
'type' => 'string',
'context' => array( 'view', 'edit', 'embed' ),
),
'hash' => array(
'description' => __( 'Cryptographic hash of the instance settings.' ),
'type' => 'string',
'context' => array( 'view', 'edit', 'embed' ),
),
'raw' => array(
'description' => __( 'Unencoded instance settings, if supported.' ),
'type' => 'object',
'context' => array( 'view', 'edit', 'embed' ),
),
),
),
'form_data' => array(
'description' => __( 'URL-encoded form data from the widget admin form. Used to update a widget that does not support instance. Write only.' ),
'type' => 'string',
'context' => array(),
'arg_options' => array(
'sanitize_callback' => function( $string ) {
$array = array();
wp_parse_str( $string, $array );
return $array;
},
),
),
),
);
return $this->add_additional_fields_schema( $this->schema );
}
}