Save Plugin Version Number as Option?

Question

I seem to recall seeing a tip somewhere saying that it was a best practice to save a plugin's version number as an option. I'm working through releasing a plugin, and I'm considering whether to do it, but since all the plugin does is make a widget (right now, it literally has no other options), I'm struggling to understand what I would ever do with that option. I'm already setting a constant with the version number for use in a couple places (mostly wp_enqueue_*).

Can someone either point me to a good resource or explain the use cases for saving the version number as an option?

Answer 1

You need to save the version to the database-- aka. save it "as an option"-- so that your script has a comparison case. That is, your script should...

1. Check the database for a version number
2. Compare that version number to the new version number-- a variable or constant in your plugin file.
3. Update things if need be
4. Save the new version number to the database

If all you have is a constant in your .php file. It always matches, meaning it is pretty much useless for any automated updating. Of course, you can keep track of the plugin versions with just the constant, but the point of saving it to the database is to be able to automatically update things when needed.

As you say, if the plugin is simple enough it may not be necessary.

Answer 2

Basically, yes, you store it in both formats, as an option and as a constant for comparative purposes. It provides a layer of checks and balances that is no more difficult to implement than not doing it in the first place. Truth...

Refer to the following Q&A thread for some nice examples how:
^{Note: none of the code shown here is mine so full credit where credit is due!}

---

Question: Releasing new plugin version, how to rename old options keys?

m0r7if3r provides the following http://wordpress.stackexchange.com/a/49736/13418

if( $db_version < {your desired version} ) {
    // previous updates and such
    $db_version = $new_version; //put that in the database
}
if( $db_version < $current_version ) {
    create $options array
    foreach( $option as $o ) {
        if( get_option( $o['old_name'] ) ) {
            update_option( $o['new_name'], get_option( $o['old_name'] ) );
            delete_option( $o['old_name'] ); //clean up behind yourself
        }
    }
    and then update your database version again
}

which is the accepted answer to that question.

However,

One Trick Pony goes on to elaborate on that example with a nice bit of code in response...

class MyPlugin{

  const 
    OPTION_NAME = 'my_plugin_options',
    VERSION     = '1.0';

  protected
    $options  = null,

    // default options and values go here
    $defaults = array(
                  'version'     => self::VERSION, // this one should not change
                  'test_option' => 'abc',
                  'another_one' => 420, 
                );

  public function getOptions(){

    // already did the checks
    if(isset($this->options))
      return $this->options;    

    // first call, get the options
    $options = get_option(self::OPTION_NAME);

    // options exist
    if($options !== false){

      $new_version = version_compare($options['version'], self::VERSION, '!=');
      $desync = array_diff_key($this->defaults, $options) !== array_diff_key($options, $this->defaults);

      // update options if version changed, or we have missing/extra (out of sync) option entries 
      if($new_version || $desync){

        $new_options = array();

        // check for new options and set defaults if necessary
        foreach($this->defaults as $option => $value)
          $new_options[$option] = isset($options[$option]) ? $options[$option] : $value;        

        // update version info
        $new_options['version'] = self::VERSION;

        update_option(self::OPTION_NAME, $new_options);
        $this->options = $new_options;  

      // no update was required
      }else{
        $this->options = $options;     
      }


    // new install (plugin was just activated)
    }else{
      update_option(self::OPTION_NAME, $this->defaults);
      $this->options = $this->defaults; 
    }

    return $this->options; 

  }    

}

Please don't accept this answer as the correct answer, I'm just providing additional, supporting material that I have as a reference and which I think supports this topic well.

Do however show your support and up-vote their answers if you use them with any success.

Answer 3

I think you are referring to the Wrox WordPress Plugin book or perhaps something on Ozh et als Blog. I've also just read it referenced in the Apress WordPress plugin guide.

The argument is that by recording the version number in the database, then when you issue an update to the plugin, you have more control over what to 'update' ... the code looks something like this

DEFINE VERSION (1.0);

function add_settings();
if (get_option(youroptions[VERSION]) === false { 
 \\ ie first time user
    add_option(youroptions[version]) = VERSION;
    add_option(youroptions[anotheroption]) ;
}
elseif (get_option(youroptions[VERSION]) !='1.0'{ 
 \\user has old plugin ... do something for them
   add_option(youroptions[optionname])
}

Does that help? I'm using the code sample above from the Apress WP book (but I typed this in from memory).