Doctrine Migrations Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require aygon/doctrine-migrations-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Aygon\DoctrineMigrationsBundle\AygonDoctrineMigrationsBundle::class => ['all' => true],
   ];
   

2. Configure the Bundle Update config/packages/doctrine_migrations.yaml (create if missing):

   doctrine_migrations:
       dir_name: '%kernel.project_dir%/src/Migrations'
       namespace: 'App\Migrations'
       table_name: 'migration_versions'
       name: 'DoctrineMigrations'
   

3. Generate Your First Migration

   php bin/console doctrine:migrations:generate --name="Initial migration"
   

   This creates a migration file in src/Migrations/VersionYYYYMMDDHHMMSS.php.

4. Execute the Migration

   php bin/console doctrine:migrations:migrate
   

First Use Case

Use this bundle to version-control database schema changes (e.g., adding a column, modifying a table). For example:

# After altering a schema in your entities:
php bin/console doctrine:migrations:diff
php bin/console doctrine:migrations:generate --name="Add user_email_index"
php bin/console doctrine:migrations:migrate

Implementation Patterns

Workflow Integration

1. Schema Changes → Migration → Deployment

   • Modify an entity (e.g., add email to User).
   • Generate a migration:

     php bin/console doctrine:migrations:diff
     php bin/console doctrine:migrations:generate --name="Add email to User"
     

   • Commit the migration file to version control.
   • Deploy and run:

     php bin/console doctrine:migrations:migrate
     

2. Rollbacks Use --down to revert:

   php bin/console doctrine:migrations:migrate --down
   

   Or target a specific version:

   php bin/console doctrine:migrations:migrate 20230101000000
   

3. Testing Migrations In phpunit.xml, add:

   <env name="KERNEL_CLASS" value="App\Kernel"/>
   <env name="SYMFONY_DEPRECATIONS_HELPER" value="weak"/>
   

   Run migrations in tests with:

   php bin/console doctrine:migrations:migrate --env=test
   

Advanced Patterns

• Custom Migration Classes Extend Doctrine\Migrations\AbstractMigration for non-schema changes (e.g., data seeding):

  namespace App\Migrations;
  
  use Doctrine\Migrations\AbstractMigration;
  use Doctrine\DBAL\Schema\Schema;
  
  class Version20230101000001 extends AbstractMigration
  {
      public function up(Schema $schema): void
      {
          $this->addSql('INSERT INTO users (id, email) VALUES (1, "test@example.com")');
      }
  }
  

• Environment-Specific Migrations Use --env=prod or --env=dev to target specific configurations.

• Dry Runs Preview SQL without executing:

  php bin/console doctrine:migrations:migrate --dry-run
  

Gotchas and Tips

Common Pitfalls

1. Namespace/Path Mismatches

   • Ensure dir_name and namespace in doctrine_migrations.yaml match your migration files.
   • Example error: Class 'App\Migrations\Version...' not found → Verify the namespace and file location.

2. Database Connection Issues

   • Migrations use the default Doctrine connection. If you have multiple connections, specify one:

     doctrine_migrations:
         connection: 'secondary_db'
     

3. Locking Conflicts

   • Migrations lock the migration_versions table. Avoid running multiple migration processes simultaneously.
   • Use --allow-no-migration to bypass checks (not recommended for production).

4. Schema Changes Without Migrations

   • Never alter the database directly (e.g., via phpMyAdmin). Always use migrations to avoid version drift.

5. Time-Based Naming Collisions

   • If migrations are generated in rapid succession, use --name explicitly to avoid VersionYYYYMMDDHHMMSS clashes.

Debugging Tips

• Check Migration Status

  php bin/console doctrine:migrations:status
  

• View Executed SQL Enable Doctrine logging in config/packages/dev/doctrine.yaml:

  dbal:
      logging: true
      profiling: true
  

• Reset Migrations (Dangerous!) To start fresh (e.g., for local development):

  php bin/console doctrine:migrations:version --delete --all
  php bin/console doctrine:migrations:migrate
  

Extension Points

1. Custom Migration Commands Extend the bundle by creating a custom command:

   namespace App\Command;
   
   use Symfony\Component\Console\Command\Command;
   use Symfony\Component\Console\Input\InputInterface;
   use Symfony\Component\Console\Output\OutputInterface;
   use Doctrine\Migrations\Configuration\Connection\ExistingConnection;
   use Doctrine\Migrations\Configuration\Migration\PhpFile;
   
   class CustomMigrationCommand extends Command
   {
       protected function configure(): void
       {
           $this->setName('app:migrate:custom');
       }
   
       protected function execute(InputInterface $input, OutputInterface $output): int
       {
           $config = new PhpFile('src/Migrations');
           $connection = new ExistingConnection(/* your connection */);
           $migration = new \Doctrine\Migrations\Tools\Console\Command\MigrateCommand();
           return $migration->run($input, $output, $config, $connection);
       }
   }
   

2. Post-Migration Hooks Use the postMigrate event in a listener:

   namespace App\EventListener;
   
   use Doctrine\Migrations\Event\PostMigrationEventArgs;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class MigrationSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents(): array
       {
           return [
               'migrations.post_migrate' => 'onPostMigrate',
           ];
       }
   
       public function onPostMigrate(PostMigrationEventArgs $args): void
       {
           // Send notification, log, or trigger other actions
       }
   }
   

3. Multi-Database Support For multi-DB setups, configure separate migration tables per connection:

   doctrine_migrations:
       connections:
           default:
               table_name: 'migration_versions'
           secondary:
               table_name: 'migration_versions_secondary'