Enhance upgrade process for plugins

[jonasraoni]

Problem

When upgrading a plugin, it should be given an opportunity to run its upgrades, also, when removing it, there should be some room to perform cleanups (e.g. drop entities, files, settings).

Introduction notes

• The Plugin class runs a single migration (fed by the getInstallMigration()), which is executed after the Installer::postInstall hook is called.

• When installing/upgrading plugins through the UI, the class PluginHelper intermediates the process.

  • When installing a fresh plugin, it does a new Install(), which looks for a install.xml (see https://github.com/pkp/ojs/blob/main/dbscripts/xml/install.xml for reference) at the plugin's root path.
  • When upgrading, if the file upgrade.xml exists, it does a new Upgrade(), otherwise, the class isn't instantiated, which means the hook Installer::postInstall won't be called and won't trigger the migration.

• On another hand, the CLI tool installPluginVersion.php has a different behavior. It always does a new Upgrade(), which triggers the migration, but it doesn't attempt to load the install.xml nor the upgrade.xml.

• Removing, then re-installing a plugin might have unexpected issues (dirty data, attempting to create something that already exists, ...)

• At this moment, if we place a plugin in the right place, the application will automatically register it in the database when accessing the Website Settings > Plugins, but the migration isn't called. This way, a user might enable a defective plugin.

Solution

• For standardization purposes, the plugin should use the same installation process of the application, which for now, relies on the *.xml files.

• The Plugin::getInstallMigration() should probably be deprecated. Before calling it, we need to check if the plugin has an install.xml/upgrade.xml.

• The CLI installPluginVersion.php should have the same behavior of the PluginHelper, and use the XML files.

• To improve the plugin removal, there could be a uninstall.xml. If it doesn't exist, then we should call the Plugin::getInstallMigration()?->down(). I might be useful to ask if the user wants to leave data (plugin settings, entities, etc), perhaps to perform a "file repair". Running the migrations in reverse order should probably work in most of cases, but it's not very performatic and might fail (irreversible upgrades).

About manual interventions from an administrator:

• After upgrading a plugin manually (e.g. git pull), the administrator should manually execute the installPluginVersion.php. And while this step isn't completed, we should probably block the plugin from being registered/executed and log an error message.

• We shouldn't auto-register plugins when accessing the Website Settings > Plugins.

• If the administrator removes a plugin from the folder, its version will be kept in the database (we might try to clean it or not), but this shouldn't block him from re-installing (the current behavior ends up emitting a warning that the plugin is already installed).

Related:
#7531
#4679

Plugins that might make use of this:
pkp/customLocale#16 (comment)

Who is asking for this feature?
Developer