WordPress.org
Get WordPress

Make WordPress Core

Changeset 51705


Ignore:
Timestamp:
08/31/2021 07:57:20 PM (3 years ago)
Author:
hellofromTonya
Message:

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.

Location:
trunk
Files:
8 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-admin/includes/upgrade.php

    r51088 r51705  
    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 );

  • trunk/src/wp-admin/widgets-form.php

    r51061 r51705  
    119119);
    120120
    121 retrieve_widgets();
     121sync_registered_widgets();
    122122
    123123// We're saving a widget without JS.

  • trunk/src/wp-includes/class-wp-customize-widgets.php

    r51700 r51705  
    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().
    … …  
    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.
    … …  
    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.

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

    r51408 r51705  
    9999     */
    100100    public function get_items( $request ) {
    101         retrieve_widgets();
     101        sync_registered_widgets();
    102102
    103103        $data = array();
    … …  
    138138     */
    139139    public function get_item( $request ) {
    140         retrieve_widgets();
     140        sync_registered_widgets();
    141141
    142142        $sidebar = $this->get_sidebar( $request['id'] );

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

    r51657 r51705  
    110110     */
    111111    public function get_items( $request ) {
    112         retrieve_widgets();
     112        sync_registered_widgets();
    113113
    114114        $prepared = array();
    … …  
    152152     */
    153153    public function get_item( $request ) {
    154         retrieve_widgets();
     154        sync_registered_widgets();
    155155
    156156        $widget_id  = $request['id'];
    … …  
    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         *
    … …  
    249249        wp_get_sidebars_widgets();
    250250
    251         retrieve_widgets();
     251        sync_registered_widgets();
    252252
    253253        $widget_id  = $request['id'];
    … …  
    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         *
    … …  
    325325        wp_get_sidebars_widgets();
    326326
    327         retrieve_widgets();
     327        sync_registered_widgets();
    328328
    329329        $widget_id  = $request['id'];

  • trunk/src/wp-includes/theme.php

    r51578 r51705  
    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.

  • trunk/src/wp-includes/widgets.php

    r51391 r51705  
    12521252    }
    12531253
    1254     retrieve_widgets( true );
    1255 }
    1256 
    1257 /**
    1258  * Look for "lost" widgets, this has to run at least on each theme change.
     1254    sync_registered_widgets( true );
     1255}
     1256
     1257/**
     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 */
     1269function 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.
    … …  
    12681285 * @return array Updated sidebars widgets.
    12691286 */
    1270 function retrieve_widgets( $theme_changed = false ) {
     1287function sync_registered_widgets( $theme_changed = false ) {
    12711288    global $wp_registered_sidebars, $sidebars_widgets, $wp_registered_widgets;
    12721289

  • trunk/tests/phpunit/tests/widgets.php

    r51568 r51705  
    844844     * Tests for when 'sidebars_widgets' theme mod is populated.
    845845     *
    846      * @covers ::retrieve_widgets
    847      */
    848     function test_retrieve_widgets_with_theme_mod() {
     846     * @covers ::sync_registered_widgets
     847     */
     848    function test_sync_registered_widgets_with_theme_mod() {
    849849        global $sidebars_widgets, $_wp_sidebars_widgets;
    850850
    … …  
    874874        );
    875875
    876         $result = retrieve_widgets( true );
     876        $result = sync_registered_widgets( true );
    877877
    878878        $this->assertIsArray( $result );
    … …  
    907907     * Tests for when sidebars widgets matches registered sidebars.
    908908     *
    909      * @covers ::retrieve_widgets
    910      */
    911     function test_retrieve_widgets_with_sidebars_widgets_matching_registered_sidebars() {
     909     * @covers ::sync_registered_widgets
     910     */
     911    function test_sync_registered_widgets_with_sidebars_widgets_matching_registered_sidebars() {
    912912        global $sidebars_widgets;
    913913
    … …  
    922922        );
    923923
    924         $result = retrieve_widgets( true );
     924        $result = sync_registered_widgets( true );
    925925
    926926        // $sidebars_widgets matches registered sidebars.
    … …  
    945945     * Tests for when sidebars widgets doesn't match registered sidebars.
    946946     *
    947      * @covers ::retrieve_widgets
    948      */
    949     function test_retrieve_widgets_with_sidebars_widgets_not_matching_registered_sidebars() {
     947     * @covers ::sync_registered_widgets
     948     */
     949    function test_sync_registered_widgets_with_sidebars_widgets_not_matching_registered_sidebars() {
    950950        global $sidebars_widgets, $_wp_sidebars_widgets;
    951951
    … …  
    961961
    962962        // Theme changed.
    963         $result = retrieve_widgets( true );
     963        $result = sync_registered_widgets( true );
    964964
    965965        $_wp_sidebars_widgets = array();
    … …  
    10031003
    10041004        // Theme did not change.
    1005         $result = retrieve_widgets();
     1005        $result = sync_registered_widgets();
    10061006
    10071007        $_wp_sidebars_widgets = array();
    … …  
    10371037     * Tests for Customizer mode.
    10381038     *
    1039      * @covers ::retrieve_widgets
    1040      */
    1041     function test_retrieve_widgets_for_customizer() {
     1039     * @covers ::sync_registered_widgets
     1040     */
     1041    function test_sync_registered_widgets_for_customizer() {
    10421042        global $sidebars_widgets, $_wp_sidebars_widgets;
    10431043
    … …  
    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();
    … …  
    10831083    }
    10841084
    1085     function test_retrieve_widgets_with_single_widget() {
     1085    function test_sync_registered_widgets_with_single_widget() {
    10861086        global $sidebars_widgets;
    10871087
    … …  
    11001100
    11011101        // Theme changed.
    1102         $result = retrieve_widgets( true );
     1102        $result = sync_registered_widgets( true );
    11031103
    11041104        $this->assertContains( 'single', $result['wp_inactive_widgets'] );
    … …  
    11081108     * Tests for orphaned widgets being moved into inactive widgets.
    11091109     *
    1110      * @covers ::retrieve_widgets
    1111      */
    1112     function test_retrieve_widgets_move_orphaned_widgets_to_inactive() {
     1110     * @covers ::sync_registered_widgets
     1111     */
     1112    function test_sync_registered_widgets_move_orphaned_widgets_to_inactive() {
    11131113        global $sidebars_widgets;
    11141114
    … …  
    11231123        );
    11241124
    1125         retrieve_widgets();
     1125        sync_registered_widgets();
    11261126
    11271127        $this->assertIsArray( $sidebars_widgets );
Note: See TracChangeset for help on using the changeset viewer.