Plugin upgrading: Widget settings

I had the same problem with a plugin (how to update the widget options in old instances when upgrading), and I have solved as follows:

STEP 1: CHECKING PLUGIN UPGRADES

You can use the upgrader_process_complete hook, but it only fires in automatic WordPress updates, not if you manually upload the plugin. You can see an example of this hook in the code reference at developer.wordpress.org.

So, I have done it with a version control: 1.- defining a constant of the new/current version, and 2.- Saving this value in wp_options once we have made the updating process.

Example: if ( $saved_version != CURRENT_VERSION ) $needs_update = true;

Also you can use the version_compare() php function.

STEP 2: UPDATING OPTIONS

Create a new method in the WP_Widget class and call it from the constructor, for example $this->mywidget_check_version().

This method checks if there is a version change (as explained in step 1), and can access all the widget instances with $this->get_settings().

With a foreach() you only need to read each instance and update the keys and values you want. You only need to maintain the instance id. For example you can create a new array to add and remove new/old keys and values:

$new_instances[$id][$key] = isset( $old_instances[$id][$key] ? $old_instances[$id][$key] : $default_value[$key];

Once done, update with $this->save_settings($new_instances) and update the version key in wp_options.

Use these WP_Widget methods instead of get_option()/update_option(), to ensure integrity and compatibility. WP_Widget defines the wp_options key, the instances ids and also adds the key $settings['_multiwidget'] = 1.

Regards.

Fernando.

Just to weigh in from a different angle - rather than auto-upgrade all settings on plugin update, simply check for an "old" setting & map to "new" settings on-the-fly:

function widget( $args, $instance ) {
    if ( isset( $instance['old_setting'] ) )
         $instance = self::_version_compat( $instance );
}

static function _version_compat( $instance ) {
    $instance['new_setting'] = $instance['old_setting'];
    // etc.

    return $instance;
}

I've did a quick test on just changing the option and it seems to work.

What I did is:

1. Wrote a widget that has just 2 fields: "Title" and "Name". Add several instances of this widget to my sidebars. Been sure that they are shown correctly in frontend.
2. Edited the class to use 3 fields: "Title" and "First Name" (to replace "Name") and added "Last Name".

3. Edited the function that register the widget on 'widgets_init' to call a function that update the widget options:

   add_action( 'widgets_init', 'my_example_widget_register' );
   
   function my_example_widget_register() {
   
     $widget_name = 'my_example_widget';  // <-- You will probably replace this
   
     $options = get_option("widget_{$widget_name}");
   
     // if the widget is not updated, run a function that updates it
     if ($options && ! get_option("is_{$widget_name}_updated")) {
         // use class below to update options
         $updater = new MyExampleWidgetUpdater($widget_name, $options);
         $updater->update();
     }
   
     register_widget('My_Example_Widget'); // <-- You will probably replace this
   }
   

4. Wrote a simple class to update widget options:

   class MyExampleWidgetUpdater
   {
   
     private $name;
     private $options;
   
     public function __construct($name, $options) {
        $this->name = $name;
        $this->options = $options;
     }
   
     public function update() {
       // loop all the options
       array_walk($this->options, function(&$option, $key) {
           if (is_array($option) && is_numeric($key)) {
             $option = $this->getOption($option);
           }
       });
       // update all options in DB
       update_option("widget_{$this->name}", $this->options);
       // set the widget as updated
       update_option("is_{$this->name}_updated", 1);
     }
   
     private function getOption($options) {
       if (!isset($options['name'])) {
          return $options;
       }
       $options['first_name'] = $options['name'];
       $options['last_name'] = '';
       unset($options['name']);
       return $options;
     }
   }
   

5. I edited the widget class to save the option "is_{$widget_name}_updated" inside the update() method, in this way the updater class will never be called for new users that never installed old widget

   class My_Example_Widget {
   
       ...
   
       public function update($new_instance, $old_instance) {
           ...
   
           $widget_name = 'my_example_widget';
           update_option("is_{$widget_name}_updated", 1);
       }
   }
   

6. I visited my site and the widgets saved with old options are displayed with no issue using new options. (Of course "last name" is always empty).

A good idea may be replace the "is_{$widget_name}_updated" option, with an option that store the actual version of the widget, in this way it will be handy next time you need an update.

Off the top of my head, each instance of a widget is given some sort of unique ID. I want to say that becomes a prexfix to the keys for the widget.

I remember poking at this some time ago but can't remember what the exacts were, sorry.