Doctrine Migrations Extra Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the package:

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

2. Enable the bundle in config/bundles.php:

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

3. Override Doctrine Migrations 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'
   

First Use Case: Dependency-Aware Migrations

Define migration dependencies in config/packages/sylius_labs_doctrine_migrations_extra.yaml:

sylius_labs_doctrine_migrations_extra:
    migrations:
        'Core\Migrations': ~
        'Plugin\Migrations': ['Core\Migrations']

Run migrations with:

php bin/console doctrine:migrations:migrate

Implementation Patterns

Topological Sorting Workflow

1. Define dependencies in sylius_labs_doctrine_migrations_extra.yaml:

   migrations:
       'Bundle1\Migrations': ['Bundle2\Migrations']
       'Bundle2\Migrations': ~
   

2. Generate migrations with explicit namespace:

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

3. Migrate in dependency order (automatically resolved):

   php bin/console doctrine:migrations:migrate
   

Bundle Integration

1. Extend configuration in your bundle’s Extension class:

   public function prepend(ContainerBuilder $container): void {
       $container->prependExtensionConfig('sylius_labs_doctrine_migrations_extra', [
           'migrations' => [
               'Acme\Migrations' => ['Core\Migrations']
           ]
       ]);
   }
   

2. Register migrations paths in doctrine_migrations.yaml:

   doctrine_migrations:
       migrations_paths:
           'Acme\Migrations': '@AcmeBundle/Migrations'
   

Multi-Environment Strategies

• Shared config: Use %kernel.environment% to conditionally define dependencies:

  sylius_labs_doctrine_migrations_extra:
      migrations:
          'App\Migrations': ~
          'Plugin\Migrations': ['App\Migrations']  # Always depends on core
  

• Environment-specific: Override in config/packages/dev/sylius_labs_doctrine_migrations_extra.yaml:

  migrations:
      'Plugin\Migrations': ['App\Migrations', 'DevPlugin\Migrations']
  

Gotchas and Tips

Pitfalls

1. Circular Dependencies:

   • The topological sorter throws CircularDependencyException if dependencies form a loop.
   • Fix: Manually reorder or remove circular references in config.

2. Namespace Conflicts:

   • Migrations must use unique namespaces (e.g., Vendor\Bundle\Migrations).
   • Fix: Use --namespace with doctrine:migrations:diff to avoid clashes.

3. Cache Invalidation:

   • After changing dependencies, clear the cache:

     php bin/console cache:clear
     

Debugging

• Check resolved order:

  php bin/console debug:container SyliusLabs\DoctrineMigrationsExtraBundle\Comparator\TopologicalVersionComparator
  

• Log migration resolution: Enable debug mode and inspect the TopologicalVersionComparator service for dependency graphs.

Extension Points

1. Custom Comparator: Extend TopologicalVersionComparator to add logic (e.g., version-based sorting):

   class CustomComparator extends TopologicalVersionComparator {
       protected function getDependencies(Migration $migration): array {
           // Custom logic here
       }
   }
   

   Register it in doctrine_migrations.yaml:

   services:
       'Doctrine\Migrations\Version\Comparator': 'App\CustomComparator'
   

2. Dynamic Dependencies: Use the ContainerAwareVersionFactory to inject services into migrations:

   public function up(Schema $schema, Migration $migration) {
       $this->container->get('service')->doSomething();
   }
   

Performance Tips

• Batch Migrations: Group related migrations under a single namespace to reduce dependency complexity.
• Avoid Overhead: Disable topological sorting for simple projects by reverting to the default Comparator.