Doctrine Migrations Bundle Laravel Package

Getting Started

This package is a Symfony bundle, not a Laravel package. Before doing anything else, confirm you actually need it:

1. Check the fork's raison d'être. webignition/doctrine-migrations-bundle is a fork of doctrine/doctrine-migrations-bundle. Diff it against upstream (composer show -a doctrine/doctrine-migrations-bundle) to see what the fork changes — usually a PHP/Symfony version constraint bump or a patch for an abandoned branch. In a Laravel app, you almost never want this; you want doctrine/migrations directly.
2. If you're in a legacy Symfony 2/3 app, register the bundle in AppKernel.php:

   new Doctrine\Bundle\MigrationsBundle\DoctrineMigrationsBundle(),
   

   and add a doctrine_migrations: block to config.yml (at minimum dir_name: "%kernel.root_dir%/DoctrineMigrations" and namespace: Application\Migrations).
3. First command: php bin/console doctrine:migrations:status --show-versions — verifies the bundle is wired up and shows which migrations have run.

In a Laravel project, the equivalent first step is to install doctrine/migrations standalone (composer require doctrine/migrations), add vendor/bin/doctrine-migrations as your entry point, and drop a migrations.php / migrations-db.php config at project root. That's the "first use case" for a Laravel developer: generate a migration from an existing schema with doctrine-migrations diff.

Implementation Patterns

Symfony (the intended target):

• Keep migrations in app/DoctrineMigrations (Symfony 2/3) or src/Migrations with migrations_paths (Symfony 4+ config style, if this fork supports it).
• Daily workflow: diff → inspect → migrate → status → version for rollbacks.
• Use --allow-empty-diff in CI to fail fast when schema drifts unintentionally.
• Custom migration base class: point migrations_base_class at your own abstract AbstractMigration subclass to inject helpers (e.g., a now() timestamp column helper).
• Wire up to doctrine:migrations:migrate --no-interaction in your deploy hook (Capistrano/Envoy/make target), before workers restart.

Laravel-idiomatic alternative (recommended):

• doctrine/migrations + doctrine/dbal gives you the same diff, migrate, status, version, generate verbs without a bundle.
• Use it alongside Laravel's own migrations table only if you truly must — see Gotchas.
• In integration tests, run migrate --to=<version> to a fixture version, then migrate first in teardown.

Integration tips:

• Put doctrine_migration_versions (Symfony default) or a distinct table name to avoid collision with Laravel's migrations table if both coexist.
• For multi-tenant setups, override storage / table_storage to a per-tenant table.

Gotchas and Tips

• Bus factor. 1 star, 0 dependents — treat this fork as abandoned unless it pins a specific bug you need. Prefer the upstream doctrine/doctrine-migrations-bundle if your Symfony version is still supported and the fix in this fork has been merged upstream.
• Version pinning is brutal. Bundles are Symfony-coupled; this fork likely only installs against a narrow Symfony/PHP range. If composer require resolution fails, inspect the composer.json constraints in the tag rather than guessing.
• Bundle registration vs. Laravel. This bundle registers via Bundle::class / build() — it's invisible to Laravel's service container. Don't try to composer require it into a Laravel app expecting artisan commands; you'll just install dead weight.
• Commands missing? If doctrine:migrations:* don't appear in bin/console list, the bundle isn't registered, or the commands are conditionally registered when a doctrine connection exists. Check debug:container --tag=console.command.
• Two migration tables. If you run both Laravel's artisan migrate and Doctrine migrations, keep table names distinct (doctrine_migration_versions vs migrations) and never let both track the same table.
• Debugging a diff mismatch: run doctrine:migrations:diff -vvv — the bundle frequently suppresses mapping errors; the verbose flag surfaces them.
• Extension points: override the doctrine.migrations service alias, or set migrations_base_class / migrations_directory; these are the two supported points this fork likely preserves from upstream.
• Upgrade path: before committing to this fork, git diff upload upstream/vX..fork/vX in the repo — the delta is typically a one-line constraint change, meaning you can often use replace or a Composer conflict/inline-alias trick against upstream instead of adding a fork dependency.