[FR] Option to automatically trigger migrations from a module

[BenParizek]

I have a group of plugins that use shared modules and those modules define schema in one or more of the plugins where they are used. This presents a problem in that I do not know which plugin may be updated first and need to trigger the migrations in all of the plugins. This is necessary right now because migration folders are registered automatically by Craft and expect migration folders to have a one-to-one relationship with plugins.

Currently, for modules that manage shared schema, this requires at least 3 migrations, where the migrations in any plugins can just import and call safeUp on the shared migration in the module but leads to several extra steps and room for errors when managing releases.

migrations/m000000_000000_base_module_migration.php
migrations/m000000_000000_base_module_migration_plugin1.php
migrations/m000000_000000_base_module_migration_plugin2.php

The acute problem in my situation is that modules that define shared schema for us in multiple plugins have no way of triggering migrations without multiple steps or duplicate code, and more generally, modules have no way of automatically communicating to Craft to trigger schema updates like plugins do using the schemaVersion attribute.

Register Migration Roots Event

One potential approach to solving this could be something similar to EVENT_REGISTER_CP_TEMPLATE_ROOTS Event, where Craft provides an API where modules could register new migration folders to be checked when it is resolving migrations:

Event::on(View::class, View::EVENT_REGISTER_MIGRATION_ROOTS, function(RegisterMigrationRootsEvent $e) {
    $e->roots['sprout-base'] = $this->getBasePath().DIRECTORY_SEPARATOR.'migrations';
});

[brandonkelly]

This has (sortof) been added for the next 3.5 beta release.

Instead of doing something module-specific, I just added support for arbitrary migration tracks, via a new --track option on migrate commands.

You can add support for it from your Sprout plugins like so:

use craft\console\controllers\MigrateController;
use craft\db\MigrationManager;
use craft\events\RegisterMigratorEvent;
use yii\base\Event;

Event::on(
    MigrateController::class,
    MigrateController::EVENT_REGISTER_MIGRATOR,
    function(RegisterMigratorEvent $event) {
        if ($event->track === 'sprout-base') {
            $event->migrator = Craft::createObject([
                'class' => MigrationManager::class,
                'track' => 'sprout-base',
                'migrationNamespace' => 'barrelstrength\sproutbase\migrations',
                'migrationPath' => '@vendor/barrelstrength/sprout-base/src/migrations,
            ]);
            $event->handled = true;
        }
    }
);

With that in place, people could start running Sprout Base migrations like so:

./craft migrate/up --track=sprout-base

Additionally, you can have all of your Sprout plugins start using the sprout-base migration track, instead of their default plugin-specific track, by overriding their getMigrator() method:

public function getMigrator(): MigrationManager
{
    return Craft::createObject([
        'class' => MigrationManager::class,
        'track' => 'sprout-base',
        'migrationNamespace' => 'barrelstrength\\sproutbase\\migrations',
        'migrationPath' => '@vendor/barrelstrength/sprout-base/src/migrations,
    ]);
}

Note if you do this, you should give each of your plugins their own install/uninstall migrations within Sprout Base, and also override your plugins’ createInstallMigration() methods to use those plugin-specific migrations. For example:

protected function createInstallMigration()
{
    // See if there's an Install migration in the plugin’s migrations folder
    $migrator = $this->getMigrator();
    $path = $migrator->migrationPath . "forms/Install.php";

    if (!is_file($path)) {
        return null;
    }

    require_once $path;
    $class = $migrator->migrationNamespace . '\\forms\\Install';

    return new $class;
}

Might be a good idea for Sprout Base to provide its own base Plugin class, with the above two methods, and have your individual plugins’ primary classes extend that.

[BenParizek]

Thanks @brandonkelly. I'll explore this.

How do migration tracks get handled in the context of someone not updating via composer and just hitting update in the CP? Would incrementing the Plugin::$schemaVersion have any effect on what happens when running an update in the CP with this in place?

[brandonkelly]

If each of your plugins start using the sprout-base migration track, then Craft will run any new sprout-base migrations any time any of your plugins’ schema versions change.

A slight disadvantage of this approach is that all DB-related changes across all of your Sprout plugins would need to be managed centrally from sprout-base, but as I said you can still have plugin-specific install migrations, and your centralized update migrations could have checks to see if certain plugins are installed before making plugin-specific schema changes.

[michaelrog]

Seems like it'd also be possible to keep plugins using their Plugin migration tracks, and just create a plugin migration whose job is to instantiate a MigrationManager for the sprout-base track and run those migrations before proceeding with the plugin's own migration logic.

[brandonkelly]

@michaelrog Good point, that could definitely be an option.