Plugin Development: Upgrading

Previous Section: Sending Emails

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 ran 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.

Below is an example of adding a permission in version 1.1 as per the Hello World 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()
        try {
            // Added in version 1.1
            if (version_compare('1.1', $this->installedVersion()) === 1) {
                // Add permission
                $attributes = [ 'view' => true, 'create' => true, 'update' => true, 'delete' => true ];
                $this->addPermission('settings', $attributes, 'HelloWorld::lang.permission');

            return true;
        } catch (Exception $e) {
            return false;

Users of the plugin must upload the new version to their /app/Plugins folder, visit the Plugins page 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.

Plugin Upgrade Pending