Doctrine Migrations Extra Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Topological Migration Sorting: The bundle introduces a topological sorter for Doctrine migrations, enabling explicit dependency management between migration sets (e.g., Core\Migrations → Plugin\Migrations). This aligns well with modular PHP/Laravel monoliths or plugin-based architectures (e.g., Sylius, eZ Platform) where migrations must execute in a strict order.
• Container-Aware Factory: Replaces Doctrine’s default MigrationFactory with a container-aware version, allowing dynamic configuration of migrations. This is highly compatible with Symfony/Laravel’s service container but may require adjustments in standalone PHP or non-containerized setups.
• Namespace Isolation: Supports custom namespaces for migrations (e.g., App\Migrations), which is critical for large codebases with overlapping migration paths.

Key Use Cases:

• Multi-bundle/multi-plugin projects (e.g., e-commerce platforms, SaaS with modular features).
• Projects with circular dependencies between migration sets (e.g., a User migration requiring a Role migration, which in turn depends on User).
• Teams using feature flags or gradual rollouts, where migrations must be sequenced carefully.

Integration Feasibility

• Symfony/Laravel Compatibility:
  • Symfony: Officially supports 6.x–8.x (via doctrine-migrations bundle). Laravel’s doctrine/dbal and migrations packages are backward-compatible with Symfony’s doctrine-migrations, but Laravel’s Schema::create() may conflict with Doctrine’s migration system. Mitigation: Use this bundle only for Doctrine migrations, not Laravel’s native migrations.
  • Laravel: Requires Doctrine DBAL (doctrine/dbal) and Doctrine Migrations (doctrine/migrations). The bundle won’t work with Laravel’s php artisan migrate (Eloquent). Workaround: Use it only for complex schema changes managed via Doctrine.
• PHP Version: Supports 8.1–8.5, which is future-proof for most PHP projects.
• Database Agnostic: Works with any DB supported by Doctrine (PostgreSQL, MySQL, SQLite, etc.).

Blockers:

• Laravel-Eloquent Users: This bundle is not a drop-in replacement for Laravel’s migrations. Teams relying solely on Eloquent will need to dual-maintain migration systems.
• Custom Migration Loaders: If your project uses non-standard migration discovery (e.g., YAML-based), the topological sorter may need extension.

Technical Risk

Critical Questions for TPM:

1. Is this project using Symfony or Laravel?
   • If Laravel: Will you replace Eloquent migrations with Doctrine, or use this only for complex schema changes?
2. Do migrations have explicit dependencies?
   • If no: Will you need to manually define the topology in sylius_labs_doctrine_migrations_extra.yaml?
3. How are migrations currently managed?
   • If using custom scripts: Will this bundle replace or augment existing workflows?
4. What’s the DB stack?
   • If not Doctrine-supported: Will you need a custom comparator?
5. CI/CD Impact:
   • Will topological sorting break existing migration pipelines (e.g., parallel execution)?

Integration Approach

Stack Fit

Migration Path

Option 1: Greenfield Project (Symfony)

1. Install Dependencies:

   composer require doctrine/dbal doctrine/migrations sylius-labs/doctrine-migrations-extra-bundle
   

2. Configure Bundles:
   • Add to config/bundles.php:

     SyliusLabs\DoctrineMigrationsExtraBundle\SyliusLabsDoctrineMigrationsExtraBundle::class => ['all' => true],
     

   • Override services in config/packages/doctrine_migrations.yaml:

     doctrine_migrations:
         services:
             'Doctrine\Migrations\Version\MigrationFactory': 'SyliusLabs\DoctrineMigrationsExtraBundle\Factory\ContainerAwareVersionFactory'
             'Doctrine\Migrations\Version\Comparator': 'SyliusLabs\DoctrineMigrationsExtraBundle\Comparator\TopologicalVersionComparator'
     

3. Define Topology:

   # config/packages/sylius_labs_doctrine_migrations_extra.yaml
   sylius_labs_doctrine_migrations_extra:
       migrations:
           'App\Core\Migrations': ~
           'App\Plugin\Migrations': ['App\Core\Migrations']
   

4. Generate Migrations:

   php bin/console doctrine:migrations:diff --namespace=App\\Core\Migrations
   

Option 2: Existing Laravel Project

1. Install Doctrine Stack:

   composer require doctrine/dbal doctrine/migrations sylius-labs/doctrine-migrations-extra-bundle
   

2. Isolate Doctrine Migrations:
   • Create a new namespace (e.g., Doctrine\Migrations) for Doctrine-managed migrations.
   • Do not mix with Eloquent migrations (php artisan migrate).
3. Configure Symfony-Style Bundles:
   • Use Symfony’s config/bundles.php (if using Laravel’s Symfony integration, e.g., laravel/symfony).
   • For pure Laravel, wrap the bundle in a custom service provider to load it post-bootstrap.
4. Define Topology:

   # config/packages/sylius_labs_doctrine_migrations_extra.yaml
   sylius_labs_doctrine_migrations_extra:
       migrations:
           'Doctrine\Migrations\Core': ~
           'Doctrine\Migrations\Plugin': ['Doctrine\Migrations\Core']
   

5. Run Migrations:

   php bin/console doctrine:migrations:execute --up-to-date
   

Option 3: Incremental Adoption

1. Start with a Single Migration Set:
   • Apply the bundle to one plugin/bundle (e.g., Auth\Migrations).
   • Gradually add dependencies as needed.
2. Hybrid Approach:
   • Use Doctrine migrations for complex schema changes.
   • Keep Eloquent migrations for simple table updates.

Compatibility

Sequencing

1. Pre-Integration:
   • Audit existing migrations for implicit dependencies.
   • Document current execution order.