How to add new options to my WordPress plugin

If you're storing a set of options, or a single option with a schema, you should do the following:

• keep a version number stored in the database, ideally as a separate value, though if you are using a single option with an array inside it, you could store it there
• keep a version number in your plugin as a defined value in a file
• on init or admin_init, compare the value in your plugin against the value in the database
  • if they differ, run an upgrade function

This way your plugins data gets updated, even if no update/activation/deactivation occurs. Your existing method would fail if an old backup was restored, or a plugin was manually updated via FTP. This is what plugins such as GravityForms do, and they take advantage of this system to implement multiple functions to upgrade from 2 -> 3 -> 4 etc

You can also use the PHP function version_compare to use version comparisons:

https://www.php.net/manual/en/function.version-compare.php

$version = ... get version from database;
if ( ! $version ) {
    // fresh install!
    do_first_time_install_of_marcos_plugin();
} else if ( version_compare( MARCOS_PLUGIN_VERSION, $version, '>') ) {
    // the plugin version is higher than what's in the DB!
    do_marcos_plugin_upgrade();
}

I have finally found an answer in this very clear article at Sitepoint: WordPress Plugin Updates the Right Way. It is surprising I didn't get this result before, but evidently my search terms was not accurate enough.

The solution is to create a function to call when the plugin is loaded: in this function we have to check the current plugin version (which in WP Plugin Boilerplate is stored in a constant in the main plugin file) and the version number stored in the options (we must store and update the plugin version within your plugin's options). If the 2 versions are different we call our activation hook and voilà, les jeux sont fait!

So in WP Plugin Boilerplate I solved the issue this way:

in the file includes/class-plugin-name.php I have added the follwing code in the define_admin_hooks() function:

$this->loader->add_action('plugins_loaded', $plugin_admin, 'check_my_plugin_version');

Then in the admin/class-my-plugin-name-admin.php file I have added this simple function:

private function check_my_plugin_version()
{
    $options = get_option('my_plugin_options');
    $installed_version = str_replace('.', '', $options['version']);
    // MY_PLUGIN_VERSION is defined in the main plugin file
    $current_version = str_replace('.', '', MY_PLUGIN_VERSION);
    if ($installed_version !== $current_version){
        require_once plugin_dir_path( __FILE__ ) . '../includes/class-my-plugin-name-activator.php';
        My_plugin_name_Activator::activate();
    }
}

Now the options in the database are updated everytime a new version of the plugin is installed, regardless of how the plugin was updated (automatically, manually using WordPress dashboard or manually using SFTP).