Plugin Development: Upgrading

Next Section: Health Checks

It is common you may wish to update the plugin at some point after the initial version and add new settings, permissions or modify the database. This can be done by making use of the simple plugin upgrade system that can run targeted code when the currently installed version is below the new plugin version.

The upgrade code should be placed in the activate function, as this is run again on each upgrade. The installedVersion helper gives you the version installed that is currently stored in the database, and this can be compared against a static version number to allow you to run code specific to the version the feature/change was added in. The installedVersion helper will give a value of null on the first activation of the plugin, or the previously installed version if the plugin was activated and then deactivated at least once.

Below is an example of adding a permission in version 1.1 of the plugin.

    /**
     * Plugins can run an installation routine when they are activated. This
     * will typically include adding default values, initialising database tables
     * and so on.
     *
     * @return boolean
     */
    public function activate()
    {
        // Added in version 1.1
        if ($this->installedVersion() === null || version_compare('1.1', $this->installedVersion()) === 1) {
            // Add permission
            $attributes = [ 'view' => true, 'create' => true, 'update' => true, 'delete' => true ];
            $this->addPermission('settings', $attributes, 'Plugins#HelloWorld::lang.permission');
        }

        return true;
    }

Users of the plugin must upload the new version to their /addons/Plugins folder, visit the Plugins page (Settings -> General -> Plugins) in the operator panel and click the Upgrade & Reactivate link for it to run the upgrade code and continue working. The plugin must be manually updated this way and will remain deactivated until it has been done so in case it relies on anything that is set in the upgrade code to function correctly.