# retrieve_widgets()

URL: https://chugunov.pro/api-wordpress/functions/retrieve_widgets/
Проверено на WordPress 6.9, обновлено 06.08.2026.
Источник: независимый русскоязычный справочник chugunov.pro. Не является официальной документацией WordPress.

Тип: функция.
Появился в версии: 2.8.0.

## Сигнатура

```php
retrieve_widgets( string|bool $theme_changed = false ): array
```

## Описание

Например, предположим, что в теме A есть боковая панель «footer», а в теме B её нет.
После переключения с темы A на тему B все виджеты, ранее назначенные в footer, оказались бы недоступны. Эта функция обнаруживает такую ситуацию и перемещает все ранее назначенные в footer виджеты в wp_inactive_widgets.
Несмотря на слово «retrieve» в названии, эта функция фактически обновляет базу данных и глобальную переменную $sidebars_widgets. По этой причине её не следует запускать в публичной части сайта, если только значение $theme_changed не равно ‘customize’ (чтобы обойти запись в базу данных).

## Параметры

- `$theme_changed` `string|bool` — необязательный, по умолчанию `false`. Была ли изменена тема, в виде логического значения. Значение 'customize' откладывает обновления для Настройщика.

## Возвращаемое значение

`array`

## Исходный код

Файл: `wp-includes/widgets.php:1325`

```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 );

	// Replace non-array values inside the array with an empty array.
	foreach ( $sidebars_widgets as $key => $value ) {
		if ( ! is_array( $value ) ) {
			$sidebars_widgets[ $key ] = array();
		}
	}

	// 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;
}
```

## История изменений

- 2.8.0 — Introduced.

## Связанные

Использует: [`_wp_remove_unregistered_widgets`](https://chugunov.pro/api-wordpress/functions/_wp_remove_unregistered_widgets/), [`wp_map_sidebars_widgets`](https://chugunov.pro/api-wordpress/functions/wp_map_sidebars_widgets/), [`get_theme_mod`](https://chugunov.pro/api-wordpress/functions/get_theme_mod/), [`wp_set_sidebars_widgets`](https://chugunov.pro/api-wordpress/functions/wp_set_sidebars_widgets/).
Используется в: `WP_REST_Widgets_Controller::retrieve_widgets`, `WP_REST_Sidebars_Controller::retrieve_widgets`, [`_wp_sidebars_changed`](https://chugunov.pro/api-wordpress/functions/_wp_sidebars_changed/), `WP_Customize_Widgets::override_sidebars_widgets_for_theme_switch`.

Оригинал в официальной документации: https://developer.wordpress.org/reference/functions/retrieve_widgets/