Skip to content

Commit b7a495d

Browse files
hellofromtonyahellofromtonya
committed
Widgets: Rename and soft deprecate retrieve_widgets().
The original name `retrieve_widgets()` was unclear as it suggested it was a getter, i.e. getting the widgets. This function does more than get: finds orphaned widgets, assigns them to the inactive sidebar, and updates the database. The new name is `sync_registered_widgets()` which better represents what happens when this function is invoked. The original `retrieve_widgets()` function is soft deprecated to avoid unnecessary code churn downstream for developers that support more than the latest version of WordPress. Follow-up to [18630]. Props zieladam, timothyblynjacobs, andraganescu, hellofromTonya. See #53811. git-svn-id: https://develop.svn.wordpress.org/trunk@51705 602fd350-edb4-49c9-b593-d223f7449a82
1 parent 1bbc5a4 commit b7a495d

8 files changed

Lines changed: 53 additions & 36 deletions

File tree

‎src/wp-admin/includes/upgrade.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1773,7 +1773,7 @@ function upgrade_330() {
17731773

17741774
// Intentional fall-through to upgrade to the next version.
17751775
case 2:
1776-
$sidebars_widgets = retrieve_widgets();
1776+
$sidebars_widgets = sync_registered_widgets();
17771777
$sidebars_widgets['array_version'] = 3;
17781778
update_option( 'sidebars_widgets', $sidebars_widgets );
17791779
}

‎src/wp-admin/widgets-form.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,7 @@
118118
)
119119
);
120120

121-
retrieve_widgets();
121+
sync_registered_widgets();
122122

123123
// We're saving a widget without JS.
124124
if ( isset( $_POST['savewidget'] ) || isset( $_POST['removewidget'] ) ) {

‎src/wp-includes/class-wp-customize-widgets.php‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -275,9 +275,9 @@ public function override_sidebars_widgets_for_theme_switch() {
275275
add_filter( 'customize_value_old_sidebars_widgets_data', array( $this, 'filter_customize_value_old_sidebars_widgets_data' ) );
276276
$this->manager->set_post_value( 'old_sidebars_widgets_data', $this->old_sidebars_widgets ); // Override any value cached in changeset.
277277

278-
// retrieve_widgets() looks at the global $sidebars_widgets.
278+
// sync_registered_widgets() looks at the global $sidebars_widgets.
279279
$sidebars_widgets = $this->old_sidebars_widgets;
280-
$sidebars_widgets = retrieve_widgets( 'customize' );
280+
$sidebars_widgets = sync_registered_widgets( 'customize' );
281281
add_filter( 'option_sidebars_widgets', array( $this, 'filter_option_sidebars_widgets_for_theme_switch' ), 1 );
282282
// Reset global cache var used by wp_get_sidebars_widgets().
283283
unset( $GLOBALS['_wp_sidebars_widgets'] );
@@ -287,7 +287,7 @@ public function override_sidebars_widgets_for_theme_switch() {
287287
* Filters old_sidebars_widgets_data Customizer setting.
288288
*
289289
* When switching themes, filter the Customizer setting old_sidebars_widgets_data
290-
* to supply initial $sidebars_widgets before they were overridden by retrieve_widgets().
290+
* to supply initial $sidebars_widgets before they were overridden by sync_registered_widgets().
291291
* The value for old_sidebars_widgets_data gets set in the old theme's sidebars_widgets
292292
* theme_mod.
293293
*
@@ -305,7 +305,7 @@ public function filter_customize_value_old_sidebars_widgets_data( $old_sidebars_
305305
/**
306306
* Filters sidebars_widgets option for theme switch.
307307
*
308-
* When switching themes, the retrieve_widgets() function is run when the Customizer initializes,
308+
* When switching themes, the sync_registered_widgets() function is run when the Customizer initializes,
309309
* and then the new sidebars_widgets here get supplied as the default value for the sidebars_widgets
310310
* option.
311311
*

‎src/wp-includes/rest-api/endpoints/class-wp-rest-sidebars-controller.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@ public function get_items_permissions_check( $request ) {
9898
* @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
9999
*/
100100
public function get_items( $request ) {
101-
retrieve_widgets();
101+
sync_registered_widgets();
102102

103103
$data = array();
104104
foreach ( wp_get_sidebars_widgets() as $id => $widgets ) {
@@ -137,7 +137,7 @@ public function get_item_permissions_check( $request ) {
137137
* @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
138138
*/
139139
public function get_item( $request ) {
140-
retrieve_widgets();
140+
sync_registered_widgets();
141141

142142
$sidebar = $this->get_sidebar( $request['id'] );
143143

‎src/wp-includes/rest-api/endpoints/class-wp-rest-widgets-controller.php‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,7 @@ public function get_items_permissions_check( $request ) {
109109
* @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
110110
*/
111111
public function get_items( $request ) {
112-
retrieve_widgets();
112+
sync_registered_widgets();
113113

114114
$prepared = array();
115115

@@ -151,7 +151,7 @@ public function get_item_permissions_check( $request ) {
151151
* @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
152152
*/
153153
public function get_item( $request ) {
154-
retrieve_widgets();
154+
sync_registered_widgets();
155155

156156
$widget_id = $request['id'];
157157
$sidebar_id = wp_find_widgets_sidebar( $widget_id );
@@ -237,7 +237,7 @@ public function update_item( $request ) {
237237
global $wp_widget_factory;
238238

239239
/*
240-
* retrieve_widgets() contains logic to move "hidden" or "lost" widgets to the
240+
* sync_registered_widgets() contains logic to move "hidden" or "lost" widgets to the
241241
* wp_inactive_widgets sidebar based on the contents of the $sidebars_widgets global.
242242
*
243243
* When batch requests are processed, this global is not properly updated by previous
@@ -248,7 +248,7 @@ public function update_item( $request ) {
248248
*/
249249
wp_get_sidebars_widgets();
250250

251-
retrieve_widgets();
251+
sync_registered_widgets();
252252

253253
$widget_id = $request['id'];
254254
$sidebar_id = wp_find_widgets_sidebar( $widget_id );
@@ -313,7 +313,7 @@ public function delete_item( $request ) {
313313
global $wp_widget_factory, $wp_registered_widget_updates;
314314

315315
/*
316-
* retrieve_widgets() contains logic to move "hidden" or "lost" widgets to the
316+
* sync_registered_widgets() contains logic to move "hidden" or "lost" widgets to the
317317
* wp_inactive_widgets sidebar based on the contents of the $sidebars_widgets global.
318318
*
319319
* When batch requests are processed, this global is not properly updated by previous
@@ -324,7 +324,7 @@ public function delete_item( $request ) {
324324
*/
325325
wp_get_sidebars_widgets();
326326

327-
retrieve_widgets();
327+
sync_registered_widgets();
328328

329329
$widget_id = $request['id'];
330330
$sidebar_id = wp_find_widgets_sidebar( $widget_id );

‎src/wp-includes/theme.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -805,7 +805,7 @@ function switch_theme( $stylesheet ) {
805805
add_option( "theme_mods_$stylesheet", $default_theme_mods );
806806
} else {
807807
/*
808-
* Since retrieve_widgets() is called when initializing a theme in the Customizer,
808+
* Since sync_registered_widgets() is called when initializing a theme in the Customizer,
809809
* we need to remove the theme mods to avoid overwriting changes made via
810810
* the Customizer when accessing wp-admin/widgets.php.
811811
*/

‎src/wp-includes/widgets.php‎

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1251,13 +1251,30 @@ function _wp_sidebars_changed() {
12511251
$sidebars_widgets = wp_get_sidebars_widgets();
12521252
}
12531253

1254-
retrieve_widgets( true );
1254+
sync_registered_widgets( true );
12551255
}
12561256

12571257
/**
1258-
* Look for "lost" widgets, this has to run at least on each theme change.
1258+
* Do not use, deprecated.
1259+
*
1260+
* Use sync_registered_widgets() instead.
12591261
*
12601262
* @since 2.8.0
1263+
* @deprecated 5.8.1 Use sync_registered_widgets()
1264+
* @see sync_registered_widgets()
1265+
*
1266+
* @param string|bool $theme_changed
1267+
* @return array
1268+
*/
1269+
function retrieve_widgets( $theme_changed = false ) {
1270+
return sync_registered_widgets( $theme_changed );
1271+
}
1272+
1273+
/**
1274+
* Looks for "lost" widgets and Updates widgets-to-sidebars allocation.
1275+
* This has to run at least on each theme change.
1276+
*
1277+
* @since 5.8.1
12611278
*
12621279
* @global array $wp_registered_sidebars Registered sidebars.
12631280
* @global array $sidebars_widgets
@@ -1267,7 +1284,7 @@ function _wp_sidebars_changed() {
12671284
* of 'customize' defers updates for the Customizer.
12681285
* @return array Updated sidebars widgets.
12691286
*/
1270-
function retrieve_widgets( $theme_changed = false ) {
1287+
function sync_registered_widgets( $theme_changed = false ) {
12711288
global $wp_registered_sidebars, $sidebars_widgets, $wp_registered_widgets;
12721289

12731290
$registered_sidebars_keys = array_keys( $wp_registered_sidebars );

‎tests/phpunit/tests/widgets.php‎

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -843,9 +843,9 @@ function register_sidebars( $sidebars ) {
843843
/**
844844
* Tests for when 'sidebars_widgets' theme mod is populated.
845845
*
846-
* @covers ::retrieve_widgets
846+
* @covers ::sync_registered_widgets
847847
*/
848-
function test_retrieve_widgets_with_theme_mod() {
848+
function test_sync_registered_widgets_with_theme_mod() {
849849
global $sidebars_widgets, $_wp_sidebars_widgets;
850850

851851
wp_widgets_init();
@@ -873,7 +873,7 @@ function test_retrieve_widgets_with_theme_mod() {
873873
'wp_inactive_widgets' => array(),
874874
);
875875

876-
$result = retrieve_widgets( true );
876+
$result = sync_registered_widgets( true );
877877

878878
$this->assertIsArray( $result );
879879
$this->assertSame( $result, $sidebars_widgets );
@@ -906,9 +906,9 @@ function test_retrieve_widgets_with_theme_mod() {
906906
/**
907907
* Tests for when sidebars widgets matches registered sidebars.
908908
*
909-
* @covers ::retrieve_widgets
909+
* @covers ::sync_registered_widgets
910910
*/
911-
function test_retrieve_widgets_with_sidebars_widgets_matching_registered_sidebars() {
911+
function test_sync_registered_widgets_with_sidebars_widgets_matching_registered_sidebars() {
912912
global $sidebars_widgets;
913913

914914
wp_widgets_init();
@@ -921,7 +921,7 @@ function test_retrieve_widgets_with_sidebars_widgets_matching_registered_sidebar
921921
'wp_inactive_widgets' => array(),
922922
);
923923

924-
$result = retrieve_widgets( true );
924+
$result = sync_registered_widgets( true );
925925

926926
// $sidebars_widgets matches registered sidebars.
927927
$this->assertIsArray( $result );
@@ -944,9 +944,9 @@ function test_retrieve_widgets_with_sidebars_widgets_matching_registered_sidebar
944944
/**
945945
* Tests for when sidebars widgets doesn't match registered sidebars.
946946
*
947-
* @covers ::retrieve_widgets
947+
* @covers ::sync_registered_widgets
948948
*/
949-
function test_retrieve_widgets_with_sidebars_widgets_not_matching_registered_sidebars() {
949+
function test_sync_registered_widgets_with_sidebars_widgets_not_matching_registered_sidebars() {
950950
global $sidebars_widgets, $_wp_sidebars_widgets;
951951

952952
wp_widgets_init();
@@ -960,7 +960,7 @@ function test_retrieve_widgets_with_sidebars_widgets_not_matching_registered_sid
960960
);
961961

962962
// Theme changed.
963-
$result = retrieve_widgets( true );
963+
$result = sync_registered_widgets( true );
964964

965965
$_wp_sidebars_widgets = array();
966966
$this->assertIsArray( $result );
@@ -1002,7 +1002,7 @@ function test_retrieve_widgets_with_sidebars_widgets_not_matching_registered_sid
10021002
);
10031003

10041004
// Theme did not change.
1005-
$result = retrieve_widgets();
1005+
$result = sync_registered_widgets();
10061006

10071007
$_wp_sidebars_widgets = array();
10081008
$this->assertIsArray( $result );
@@ -1036,9 +1036,9 @@ function test_retrieve_widgets_with_sidebars_widgets_not_matching_registered_sid
10361036
/**
10371037
* Tests for Customizer mode.
10381038
*
1039-
* @covers ::retrieve_widgets
1039+
* @covers ::sync_registered_widgets
10401040
*/
1041-
function test_retrieve_widgets_for_customizer() {
1041+
function test_sync_registered_widgets_for_customizer() {
10421042
global $sidebars_widgets, $_wp_sidebars_widgets;
10431043

10441044
wp_widgets_init();
@@ -1053,7 +1053,7 @@ function test_retrieve_widgets_for_customizer() {
10531053
);
10541054
set_theme_mod( 'sidebars_widgets', $old_sidebars_widgets );
10551055

1056-
$result = retrieve_widgets( 'customize' );
1056+
$result = sync_registered_widgets( 'customize' );
10571057

10581058
$_wp_sidebars_widgets = array();
10591059
$this->assertIsArray( $result );
@@ -1082,7 +1082,7 @@ function test_retrieve_widgets_for_customizer() {
10821082
$this->assertNotEquals( $sidebars_widgets, wp_get_sidebars_widgets() );
10831083
}
10841084

1085-
function test_retrieve_widgets_with_single_widget() {
1085+
function test_sync_registered_widgets_with_single_widget() {
10861086
global $sidebars_widgets;
10871087

10881088
wp_widgets_init();
@@ -1099,17 +1099,17 @@ function test_retrieve_widgets_with_single_widget() {
10991099
);
11001100

11011101
// Theme changed.
1102-
$result = retrieve_widgets( true );
1102+
$result = sync_registered_widgets( true );
11031103

11041104
$this->assertContains( 'single', $result['wp_inactive_widgets'] );
11051105
}
11061106

11071107
/**
11081108
* Tests for orphaned widgets being moved into inactive widgets.
11091109
*
1110-
* @covers ::retrieve_widgets
1110+
* @covers ::sync_registered_widgets
11111111
*/
1112-
function test_retrieve_widgets_move_orphaned_widgets_to_inactive() {
1112+
function test_sync_registered_widgets_move_orphaned_widgets_to_inactive() {
11131113
global $sidebars_widgets;
11141114

11151115
wp_widgets_init();
@@ -1122,7 +1122,7 @@ function test_retrieve_widgets_move_orphaned_widgets_to_inactive() {
11221122
'orphaned_widgets_1' => array( 'calendar-1' ),
11231123
);
11241124

1125-
retrieve_widgets();
1125+
sync_registered_widgets();
11261126

11271127
$this->assertIsArray( $sidebars_widgets );
11281128

0 commit comments

Comments
 (0)