Changeset 51842

Timestamp:

09/21/2021 10:12:18 PM (21 months ago)

Author:

azaozz

Message:

Update and enhance the docs for retrieve_widgets().

Props zieladam, hellofromtonya.
Fixes #53811.

File:

• trunk/src/wp-includes/widgets.php (modified) (2 diffs)

trunk/src/wp-includes/widgets.php

@@ -1256 +1256 @@
 
 /**
- * Look for "lost" widgets, this has to run at least on each theme change.
+ * Validates and remaps any "orphaned" widgets to wp_inactive_sidgets sidebar, and saves the widget settings.
+ * This has to run at least on each theme change.
+ *
+ * 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 from the front end unless the param value is 'customize' (to bypass the database write).
  *
  * @since 2.8.0
@@ -1311 +1319 @@
 
     if ( 'customize' !== $theme_changed ) {
+        // Update the widgets settings in the database.
         wp_set_sidebars_widgets( $sidebars_widgets );
     }