Simplytestable Base Migrations Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package — there is no service provider or loadMigrationsFrom(). Treat it as a shared library of Doctrine migration classes plus whatever wiring registers its Migrations/ directory with doctrine/doctrine-migrations-bundle.

Minimal steps:

1. Confirm the package still installs against your stack. It is effectively unmaintained (1 star, 0 dependents), so check composer.json constraints for symfony/* and doctrine/migrations before committing.

   composer require webignition/simplytestable-base-migrations-bundle
   

2. Register the bundle the Symfony way:
   • Symfony 4/5+: add Webignition\SimplyTestableBaseMigrationsBundle\SimplyTestableBaseMigrationsBundle::class => ['all' => true] to config/bundles.php.
   • Symfony 3: add it to AppKernel::registerBundles().
3. Ensure DoctrineMigrationsBundle is installed and configured; this bundle is only useful as an addition to it.
4. Look first at, in this order:
   • SimplyTestableBaseMigrationsBundle.php (the bundle class — check getPath() and any compiler pass),
   • Resources/config/ for service/DI wiring,
   • Migrations/ for the actual AbstractMigration subclasses,
   • composer.json for the hard version constraints.
5. First use case: run the base migrations once per application (app.simplytestable.com and worker.simplytestable.com) before that app's own migrations:

   bin/console doctrine:migrations:migrate --no-interaction
   

If the bundle does not auto-register its migration path, you will have to add it manually via doctrine_migrations.migrations_paths (see below).

Implementation Patterns

Shared-base, per-app overlay. The intended model is a two-layer migration set: this bundle owns the baseline schema common to both apps; each app keeps its own Migrations/ directory for app-specific changes. Configure the base path first so ordering is deterministic:

# config/packages/doctrine_migrations.yaml
doctrine_migrations:
    migrations_paths:
        'Webignition\SimplyTestableBaseMigrations': '%kernel.project_dir%/vendor/webignition/simplytestable-base-migrations-bundle/Migrations'
        'App\Migrations': '%kernel.project_dir%/migrations'

Version pinning between the two apps. Since both consumers must agree on the base schema, require an exact tag in both composer.json files ("webignition/simplytestable-base-migrations-bundle": "1.2.3") and bump them in lockstep. A floating constraint here causes the two apps to diverge silently.

Deploy-pipeline integration. Run migrations as an explicit deploy step, not on container boot. In each app's pipeline:

bin/console doctrine:migrations:migrate --no-interaction --allow-no-migration

Run the app with more schema surface first (usually app), then worker, so the worker never starts against a half-migrated schema.

Local development with a path repository. Because the package is unlikely to receive fixes, vendor it as a path repo while you adapt it:

"repositories": [{ "type": "path", "url": "../simplytestable-base-migrations-bundle" }]

Laravel analogue. If you are porting the idea rather than the code: publish the base migrations into a small Composer package and call $this->loadMigrationsFrom(__DIR__.'/../database/migrations') from a service provider. That gives you the same shared-base behaviour without the Symfony/Doctrine coupling.

Gotchas and Tips

• Maintenance risk is the headline. One star and zero dependents means no upstream fixes. Fork it into your own VCS and pin to the fork before you build a deploy process around it. Assume you own the code.
• Version constraints will bite first. Old Symfony bundles typically pin symfony/symfony or doctrine/migrations to majors that are EOL. If composer require fails, do not fight it with --ignore-platform-reqs; fork and relax the constraints deliberately.
• Migration ordering is by version timestamp, not by path order. Doctrine sorts by the version embedded in the class name, not by the order of migrations_paths. Make sure base migrations carry earlier versions than anything in the app's Migrations/ directory, or a later app migration will run before the schema it depends on.
• Shared migration_versions table. If both apps point at the same database, they share the migration metadata table and will see each other's applied versions — usually what you want, but it means an app-specific migration run by one app is marked applied for the other. If they use separate databases, this is a non-issue; verify which model you are in before debugging "skipped" migrations.
• Namespace collisions. If the app already has a migration class with the same fully-qualified name as one in the bundle, Doctrine's class loader resolution is ambiguous. Keep bundle migrations namespaced under the bundle namespace and never copy them into the app.
• Cache after install. Bundle registration changes are invisible until bin/console cache:clear; a "migrations path not found" error immediately after composer require is almost always a stale container.
• Debugging commands. doctrine:migrations:list shows which paths Doctrine actually knows about — use it first when the bundle's migrations do not appear. doctrine:migrations:migrate --dry-run and doctrine:migrations:status are your next stops.
• Extension point. If the bundle's path registration is wrong for your layout, the clean fix is a small compiler pass in your app that appends the bundle's Migrations/ directory to the migrations configuration, rather than editing the bundle in vendor/.
• Do not attempt to use this in Laravel. There is no bridge, and the effort of one is larger than reimplementing the shared-migration pattern natively.