Hotaru Docs

 [həʊdɒks]

Install and Upgrade Functions

The install function is used for both installing and upgrading a plugin, but it's not necessary to have an install function unless you plugin needs it.

To use an install function, add the hook install_plugin in the hooks list at the top of your plugin file. When a user first installs your plugin, Hotaru will run your install function:

public function install_plugin()
{
    // code you want to run on installation
}

There are two occasions when the install function is run:

1. When the user clicks the install icon.

2. When a user activates a currently installed plugin AND its version number is greater than the version number currently stored in the database. This means that a user can "upgrade" a plugin by turning it off, overwriting the files and turning it back on - all without uninstalling it.

Potential problems

To avoid overwriting current settings or creating tables that already exist when a user upgrades or reinstalls a plugin, you need to include conditions to avoid those situations.

Consider these scenarios:

1. You create a database table in the install function:

If a user tries to upgrade or re-install your plugin, they will get an error saying the table already exists. So use this in your install_plugin function to check if your table exists before creating it:

public function install_plugin($h)
 {
    $exists = $h->db->table_exists('table_name_no_prefix');
     if (!$exists) {
         // table doesn't exist, let's create it...
     }
}

2. The user installs your plugin more than once:

To prevent database errors such as duplicate keys, we need to tell Hotaru only to alter the table if it hasn't already been done. E.g.

public function install_plugin($h)
{
    if (!$h->db->column_exists('table_name_no_prefix', 'new_column_name')) {
            // add new column
            $sql = "ALTER TABLE " . DB_PREFIX . "table_name ADD column_name varchar(32)";
            $h->db->query($h->db->prepare($sql));
        }
}

3. To avoid overwriting existing settings, you can use these:

Non-serialized settings:

if (!$h->getSetting('my_plugin_setting')) { $h->updateSetting('my_plugin_setting', 'new_value'); }

Serialized settings:

$my_settings = $h->getSerializedSettings();
if (!isset($my_settings['my_plugin_setting'])) { $my_settings['my_plugin_setting'] = "new_value"; }
$h->updateSetting('my_settings', serialize($my_settings));

In summary, when making your install function consider how to handle the existing database structure and plugin settings.

Getting StartedDesign and LayoutPlugin DevelopmentAdvanced TopicsFunction ReferenceTroubleshooting