[6.x] Allowing a plugin to run additional migration tracks

[BenParizek]

In Craft 5, we could override the craft\db\MigrationManager class on a plugins getMigrator method and customize the functionality. In Craft 6, currently, it seems that this class has changed to CraftCms\Cms\Database\Migrator and has been declared final final class Migrator extends \Illuminate\Database\Migrations\Migrator so it can no longer be extended and it appears the only way to customize migration needs at the moment is via something like the MigrationsStarted event which could potentially have side effects.

The issue I'm trying to solve is that I have a plugin that depends on certain additional migrations managed in a separate Laravel package and has a different migration track. Ideally, I would not have to communicate any details about this to a Craft user. They could just run the Craft plugin migrations as they normally do, and my code sorts out what migrations need to run.

Currently, I think, Craft assumes there are only 3 types of migration tracks (craft, content, and plugin:* and I don't see a way to introduce a "module" or "other" track.

On Craft 5 I solved this by extending the MigrationManager and adding the logic I needed for the additional tracks. Is there some option to do this that I'm missing?

If not, would Craft consider adding support within the migration logic and giving plugins some way to let Craft know what other migration tracks need to be run when a given plugin is installed/updated?

[riasvdv]

6.x currently has no fixed set of tracks and you can use the Migrator with any track.

You can retrieve the migrator either using dependency injection or app(\CraftCms\Cms\Database\Migrator::class), you can then call ->track() on it with your own track (which will tell the database repository on which track to filter).

You'll also need to call ->setPaths() on it to tell the migrator where to look for your migration files or pass them to the ->run() method.

You can see for reference how the Plugin determines the paths & track to run https://github.com/craftcms/cms/blob/6.x/src/Plugin/Concerns/Installable.php#L73-L80

[BenParizek]

Thanks @riasvdv. Can you help me connect the dots here? I understand what your saying about creating a Migrator with a custom track or path. What I'm still struggling to see is where to fit this into my custom code so that when a user runs the normal migrate/all command in the context of an installation and update.

Perhaps one more detail that I didn't mention in my first comment is that I'd like to have a single plugin do this for multiple custom tracks. The Plugin::getMigrator() method from the Installable Concern let's me return a different Migrator, but it appears the ->track() only takes a singular track. So in the scenario where I have multiple tracks, I need to potentially return two migrators, or loop through them and run them right from the getMigrator method, which seems semantically incorrect and takes responsibility from Craft's existing plugin migration flow in deciding when those migrations are executed and how they get handled if they throw an error.

Where would you recommend that I ->run() multiple custom Migrators for a single plugin during the default Craft install or update migrations for that plugin?

[riasvdv]

I've added an event which allows you to register additional migrators that are run with the php craft migrate:all command: 70a57d6

use CraftCms\Cms\Database\Events\RegisterMigrators;
use CraftCms\Cms\Database\Migrator;
use Illuminate\Support\Facades\Event;

Event::listen(RegisterMigrators::class, function (RegisterMigrators $event) {
    $event->migrators[] = app(Migrator::class)->track('my-track')->setPaths([
        // Path to migration files
    ]);
});

This is similar to how the functionality was already available as discussed here: #6172 (comment)

[BenParizek]

Thansk @riasvdv. That looks perfect.

[BenParizek]

@riasvdv One detail I've noticed is that if I run craft artisan craft/up and then say "no" to the custom migrator that's registered via this event for the "Checking for pending Craft and plugin migrations", then I get prompted for the migration again under the Content Migration track (" Checking for pending content migrations").

Running the migration works fine, but it might make sense to limit this event or provide some option in the RegisterMigrators $event to only have the custom migrator get triggered in one migration context.

[riasvdv]

Fixed! 04a6388 forgot to filter those by the track input