1. This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn More.

[Docs] Install and Upgrade Functions

Discussion in 'Developing Plugins' started by Nick, Oct 22, 2009.

  1. Nick

    Nick Well-Known Member

    This guide gives an overview of the install plugin function, when it is used and potential problems.

    As of Hotaru 0.8, there is no longer an upgrade function. The install function is used for both installing and upgrading.

    In the header of your main plugin file, add the hook install_plugin.

    Naturally, when a user first installs your plugin, Hotaru will run your install function:

    PHP:
    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:

    PHP:
    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 re-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.

    PHP:
    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:
    PHP:
    if (!$h->getSetting('my_plugin_setting')) { $h->updateSetting('my_plugin_setting''new_value'); } 
    Serialized settings:

    PHP:
    $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.
     

Share This Page