WordPress at a glance
function is not described

WP_Customize_Widgets::call_widget_update() public WP 3.9.0

Finds and invokes the widget update and control callbacks.

Requires that $_POST be populated with the instance data.

It's a method of the class: WP_Customize_Widgets{}

No Hooks.

Return

Array/WP_Error. Array containing the updated widget information. A WP_Error object, otherwise.

Usage

$WP_Customize_Widgets = new WP_Customize_Widgets();
$WP_Customize_Widgets->call_widget_update( $widget_id );
$widget_id(string) (required)
Widget ID.

Notes

  • Global. Array. $wp_registered_widget_updates
  • Global. Array. $wp_registered_widget_controls

Changelog

Since 3.9.0 Introduced.

Code of WP_Customize_Widgets::call_widget_update() WP 5.5.1

<?php
public function call_widget_update( $widget_id ) {
	global $wp_registered_widget_updates, $wp_registered_widget_controls;

	$setting_id = $this->get_setting_id( $widget_id );

	/*
	 * Make sure that other setting changes have previewed since this widget
	 * may depend on them (e.g. Menus being present for Navigation Menu widget).
	 */
	if ( ! did_action( 'customize_preview_init' ) ) {
		foreach ( $this->manager->settings() as $setting ) {
			if ( $setting->id !== $setting_id ) {
				$setting->preview();
			}
		}
	}

	$this->start_capturing_option_updates();
	$parsed_id   = $this->parse_widget_id( $widget_id );
	$option_name = 'widget_' . $parsed_id['id_base'];

	/*
	 * If a previously-sanitized instance is provided, populate the input vars
	 * with its values so that the widget update callback will read this instance
	 */
	$added_input_vars = array();
	if ( ! empty( $_POST['sanitized_widget_setting'] ) ) {
		$sanitized_widget_setting = json_decode( $this->get_post_value( 'sanitized_widget_setting' ), true );
		if ( false === $sanitized_widget_setting ) {
			$this->stop_capturing_option_updates();
			return new WP_Error( 'widget_setting_malformed' );
		}

		$instance = $this->sanitize_widget_instance( $sanitized_widget_setting );
		if ( is_null( $instance ) ) {
			$this->stop_capturing_option_updates();
			return new WP_Error( 'widget_setting_unsanitized' );
		}

		if ( ! is_null( $parsed_id['number'] ) ) {
			$value                         = array();
			$value[ $parsed_id['number'] ] = $instance;
			$key                           = 'widget-' . $parsed_id['id_base'];
			$_REQUEST[ $key ]              = wp_slash( $value );
			$_POST[ $key ]                 = $_REQUEST[ $key ];
			$added_input_vars[]            = $key;
		} else {
			foreach ( $instance as $key => $value ) {
				$_REQUEST[ $key ]   = wp_slash( $value );
				$_POST[ $key ]      = $_REQUEST[ $key ];
				$added_input_vars[] = $key;
			}
		}
	}

	// Invoke the widget update callback.
	foreach ( (array) $wp_registered_widget_updates as $name => $control ) {
		if ( $name === $parsed_id['id_base'] && is_callable( $control['callback'] ) ) {
			ob_start();
			call_user_func_array( $control['callback'], $control['params'] );
			ob_end_clean();
			break;
		}
	}

	// Clean up any input vars that were manually added.
	foreach ( $added_input_vars as $key ) {
		unset( $_POST[ $key ] );
		unset( $_REQUEST[ $key ] );
	}

	// Make sure the expected option was updated.
	if ( 0 !== $this->count_captured_options() ) {
		if ( $this->count_captured_options() > 1 ) {
			$this->stop_capturing_option_updates();
			return new WP_Error( 'widget_setting_too_many_options' );
		}

		$updated_option_name = key( $this->get_captured_options() );
		if ( $updated_option_name !== $option_name ) {
			$this->stop_capturing_option_updates();
			return new WP_Error( 'widget_setting_unexpected_option' );
		}
	}

	// Obtain the widget instance.
	$option = $this->get_captured_option( $option_name );
	if ( null !== $parsed_id['number'] ) {
		$instance = $option[ $parsed_id['number'] ];
	} else {
		$instance = $option;
	}

	/*
	 * Override the incoming $_POST['customized'] for a newly-created widget's
	 * setting with the new $instance so that the preview filter currently
	 * in place from WP_Customize_Setting::preview() will use this value
	 * instead of the default widget instance value (an empty array).
	 */
	$this->manager->set_post_value( $setting_id, $this->sanitize_widget_js_instance( $instance ) );

	// Obtain the widget control with the updated instance in place.
	ob_start();
	$form = $wp_registered_widget_controls[ $widget_id ];
	if ( $form ) {
		call_user_func_array( $form['callback'], $form['params'] );
	}
	$form = ob_get_clean();

	$this->stop_capturing_option_updates();

	return compact( 'instance', 'form' );
}