WP_REST_Widget_Types_Controller::encode_form_data( WP_REST_Request $request ): WP_REST_Response|WP_Error

An RPC-style endpoint which can be used by clients to turn user input in a widget admin form into an encoded instance object.

Description

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.

Parameters

$requestWP_REST_Requestrequired
Full details about the request.

Return

WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.

Source

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 );
	$widget_key          = $wp_widget_factory->get_widget_key( $id );

	$response = array(
		'form'     => trim(
			$this->get_widget_form(
				$widget_object,
				$instance
			)
		),
		'preview'  => trim(
			$this->get_widget_preview(
				$widget_key,
				$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 );
}

Hooks

apply_filters( ‘widget_update_callback’, array $instance, array $new_instance, array $old_instance, WP_Widget $widget )

Filters a widget’s settings before saving.

Changelog

VersionDescription
5.8.0Introduced.

User Contributed Notes

You must log in before being able to contribute a note or feedback.