Doctrine Migrations Bundle Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation Add the bundle to your Symfony project via Composer:

   composer require covex-nn/doctrine-migrations-bundle
   

   Enable the bundle in config/bundles.php:

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

2. First Use Case Run migrations to create/update your database schema:

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

   Verify migrations are registered in src/Migrations/ (auto-generated by default).

3. Where to Look First

   • Doctrine Migrations Documentation: Official Docs (this bundle is a fork, but core concepts apply).
   • Bundle Configuration: config/packages/doctrine_migrations.yaml (if created).
   • Migration Classes: src/Migrations/ for custom migrations.

Implementation Patterns

Core Workflows

1. Schema Evolution

   • Diff & Generate: Use doctrine:migrations:diff to auto-generate migrations from entity changes.
   • Manual Migrations: Create custom migrations in src/Migrations/VersionYYYYMMDDHHMMSS.php:

     namespace DoctrineMigrations;
     
     use Doctrine\DBAL\Schema\Schema;
     use Doctrine\Migrations\AbstractMigration;
     
     class Version20230101000000 extends AbstractMigration
     {
         public function up(Schema $schema): void
         {
             $this->addSql('CREATE TABLE user_preferences (...)');
         }
     
         public function down(Schema $schema): void
         {
             $this->addSql('DROP TABLE user_preferences');
         }
     }
     

   • Execute: Run doctrine:migrations:migrate or doctrine:migrations:execute 'DoctrineMigrations\VersionYYYYMMDDHHMMSS'.

2. Version Control

   • Commit migration files to version control (e.g., Git) to ensure consistency across deployments.
   • Use doctrine:migrations:status to check applied migrations.

3. Integration with CI/CD

   • Add migration checks to your pipeline:

     # Example GitHub Actions
     - name: Run migrations
       run: php bin/console doctrine:migrations:migrate --allow-no-migration
     

4. Entity-Driven Development

   • Modify entities (e.g., add a field to User.php), then generate migrations:

     php bin/console doctrine:migrations:diff
     php bin/console doctrine:migrations:migrate
     

Advanced Patterns

• Custom Migration Namespaces: Configure in config/packages/doctrine_migrations.yaml:

  doctrine_migrations:
      namespace: App\Migrations
      directory: '%kernel.project_dir%/src/Migrations'
  

• Post-Migration Scripts: Use doctrine:migrations:execute with custom SQL or PHP logic.
• Rollbacks: Test doctrine:migrations:rollback in staging before production.

Gotchas and Tips

Common Pitfalls

1. Namespace Conflicts

   • Ensure your migration namespace (e.g., App\Migrations) doesn’t clash with the bundle’s default (DoctrineMigrations).
   • Fix: Explicitly set namespace in configuration.

2. Auto-Generated Migrations

   • doctrine:migrations:diff may generate overly complex SQL for large schema changes.
   • Tip: Review and simplify migrations manually before applying to production.

3. Database Locking

   • Long-running migrations can lock the database. Test in staging first.
   • Tip: Use --write-sql to preview SQL before execution:

     php bin/console doctrine:migrations:execute 'App\Migrations\Version...' --write-sql > migration.sql
     

4. Missing Dependencies

   • The bundle requires doctrine/doctrine-migrations-bundle and doctrine/dbal.
   • Fix: Install dependencies explicitly if missing:

     composer require doctrine/doctrine-migrations-bundle doctrine/dbal
     

5. Configuration Overrides

   • The bundle may not load if doctrine_migrations.yaml is misconfigured.
   • Debug: Check Symfony’s debug output for missing configuration errors.

Debugging Tips

• Dry Runs: Use --dry-run to test migrations without applying:

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

• SQL Logging: Enable SQL logging in config/packages/dev/doctrine.yaml:

  dbal:
      logging: true
      profiling: true
  

• Migration Status: Use doctrine:migrations:status to diagnose stuck migrations.

Extension Points

1. Custom Migration Commands Extend the bundle by creating custom commands (e.g., for data migrations):

   // src/Command/CustomMigrationCommand.php
   namespace App\Command;
   
   use Symfony\Component\Console\Command\Command;
   use Symfony\Component\Console\Input\InputInterface;
   use Symfony\Component\Console\Output\OutputInterface;
   
   class CustomMigrationCommand extends Command
   {
       protected function execute(InputInterface $input, OutputInterface $output): int
       {
           // Custom logic (e.g., call doctrine:migrations:migrate + data updates)
           return Command::SUCCESS;
       }
   }
   

   Register in src/Kernel.php:

   protected function registerCommands(): void
   {
       $this->commands = [
           // ...
           new \App\Command\CustomMigrationCommand(),
       ];
   }
   

2. Event Listeners Hook into migration events (e.g., postGenerateMigration) to modify behavior:

   // src/EventListener/MigrationListener.php
   namespace App\EventListener;
   
   use Doctrine\Migrations\Event\PostGenerateMigrationEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class MigrationListener implements EventSubscriberInterface
   {
       public static function getSubscribedEvents(): array
       {
           return [
               PostGenerateMigrationEvent::NAME => 'onPostGenerateMigration',
           ];
       }
   
       public function onPostGenerateMigration(PostGenerateMigrationEvent $event): void
       {
           $migration = $event->getMigration();
           // Modify $migration->up() or $migration->down() logic
       }
   }
   

   Register in services.yaml:

   services:
       App\EventListener\MigrationListener:
           tags: ['doctrine_migrations.event_subscriber']
   

3. Database-Specific Quirks

   • Some databases (e.g., PostgreSQL) require schema-specific syntax. Use addSql() for database-agnostic migrations or conditional logic:

     public function up(Schema $schema): void
     {
         if ($this->connection->getDatabasePlatform()->getName() === 'postgresql') {
             $this->addSql('CREATE EXTENSION IF NOT EXISTS "uuid-ossp"');
         }
     }