retrieve_widgets() WordPress Function

The retrieve_widgets() function is used to return an array of all active widgets for a given sidebar. If no sidebar is specified, then all active widgets across all sidebars will be returned.

retrieve_widgets( string|bool $theme_changed = false ) #

Validates and remaps any “orphaned” widgets to wp_inactive_widgets sidebar, and saves the widget settings. This has to run at least on each theme change.


Description

For example, let’s say theme A has a "footer" sidebar, and theme B doesn’t have one. After switching from theme A to theme B, all the widgets previously assigned to the footer would be inaccessible. This function detects this scenario, and moves all the widgets previously assigned to the footer under wp_inactive_widgets.

Despite the word "retrieve" in the name, this function actually updates the database and the global $sidebars_widgets. For that reason it should not be run on front end, unless the $theme_changed value is ‘customize’ (to bypass the database write).


Top ↑

Parameters

$theme_changed

(string|bool)(Optional)Whether the theme was changed as a boolean. A value of 'customize' defers updates for the Customizer.

Default value: false


Top ↑

Return

(array) Updated sidebars widgets.


Top ↑

Source

File: wp-includes/widgets.php

function retrieve_widgets( $theme_changed = false ) {
	global $wp_registered_sidebars, $sidebars_widgets, $wp_registered_widgets;

	$registered_sidebars_keys = array_keys( $wp_registered_sidebars );
	$registered_widgets_ids   = array_keys( $wp_registered_widgets );

	if ( ! is_array( get_theme_mod( 'sidebars_widgets' ) ) ) {
		if ( empty( $sidebars_widgets ) ) {
			return array();
		}

		unset( $sidebars_widgets['array_version'] );

		$sidebars_widgets_keys = array_keys( $sidebars_widgets );
		sort( $sidebars_widgets_keys );
		sort( $registered_sidebars_keys );

		if ( $sidebars_widgets_keys === $registered_sidebars_keys ) {
			$sidebars_widgets = _wp_remove_unregistered_widgets( $sidebars_widgets, $registered_widgets_ids );

			return $sidebars_widgets;
		}
	}

	// Discard invalid, theme-specific widgets from sidebars.
	$sidebars_widgets = _wp_remove_unregistered_widgets( $sidebars_widgets, $registered_widgets_ids );
	$sidebars_widgets = wp_map_sidebars_widgets( $sidebars_widgets );

	// Find hidden/lost multi-widget instances.
	$shown_widgets = array_merge( ...array_values( $sidebars_widgets ) );
	$lost_widgets  = array_diff( $registered_widgets_ids, $shown_widgets );

	foreach ( $lost_widgets as $key => $widget_id ) {
		$number = preg_replace( '/.+?-([0-9]+)$/', '$1', $widget_id );

		// Only keep active and default widgets.
		if ( is_numeric( $number ) && (int) $number < 2 ) {
			unset( $lost_widgets[ $key ] );
		}
	}
	$sidebars_widgets['wp_inactive_widgets'] = array_merge( $lost_widgets, (array) $sidebars_widgets['wp_inactive_widgets'] );

	if ( 'customize' !== $theme_changed ) {
		// Update the widgets settings in the database.
		wp_set_sidebars_widgets( $sidebars_widgets );
	}

	return $sidebars_widgets;
}


Top ↑

Changelog

Changelog
VersionDescription
2.8.0Introduced.

The content displayed on this page has been created in part by processing WordPress source code files which are made available under the GPLv2 (or a later version) license by theĀ Free Software Foundation. In addition to this, the content includes user-written examples and information. All material is subject to review and curation by the WPPaste.com community.