Migration Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require effiana/migration-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Effiana\MigrationBundle\EffianaMigrationBundle::class => ['all' => true],
   ];
   

2. Generate a Migration Use the bundle’s command to scaffold a new migration:

   php bin/console effiana:migration:generate
   

   This creates a migration class in Migrations\Schema/{version_number}/ (e.g., Migrations\Schema/20240101000000/).

3. Define a Schema Migration Implement the Migration interface in your new class:

   namespace App\Migrations\Schema\20240101000000;
   
   use Effiana\MigrationBundle\Migration\Migration;
   use Effiana\MigrationBundle\Migration\Schema;
   
   class AddUserTable implements Migration
   {
       public function up(Schema $schema, $queries): void
       {
           $schema->createTable('users', function ($table) {
               $table->addColumn('id', 'integer', ['autoincrement' => true]);
               $table->addColumn('name', 'string', ['length' => 255]);
               $table->addPrimaryKey(['id']);
           });
       }
   }
   

4. Run the Migration Execute the migration via:

   php bin/console effiana:migration:migrate
   

First Use Case: Schema Changes

Use this bundle to version-control database schema changes (e.g., adding tables, columns, or constraints) in a portable, framework-agnostic way (via DBAL). Ideal for:

• Initial database setup.
• Backward-compatible schema updates (e.g., adding optional columns).
• Cross-database compatibility (MySQL, PostgreSQL, SQLite).

Implementation Patterns

Workflows

1. Schema-First Approach

   • Use the Schema object to define changes declaratively (e.g., createTable, addColumn, addForeignKey).
   • Example: Adding a timestamp column:

     $schema->table('users')->addColumn('created_at', 'datetime');
     

2. Query Bag for Custom SQL

   • Use queries->addPreQuery() or queries->addPostQuery() for raw SQL when DBAL lacks support (e.g., database-specific syntax).
   • Example:

     $queries->addPreQuery('CREATE EXTENSION IF NOT EXISTS "uuid-ossp";');
     

3. Fixtures for Data Migrations

   • Pair with Effiana\MigrationBundle\Migration\Fixture for data seeding (e.g., inserting default records).
   • Example:

     namespace App\Migrations\Fixtures\20240101000000;
     
     use Effiana\MigrationBundle\Migration\Fixture;
     
     class SeedUsers implements Fixture
     {
         public function load(): void
         {
             $this->insert('users', ['name' => 'Admin'], ['id' => 1]);
         }
     }
     

   • Run fixtures with:

     php bin/console effiana:migration:fixtures
     

4. Rollbacks

   • Implement a down() method in your migration to reverse changes (if needed):

     public function down(Schema $schema, $queries): void
     {
         $schema->dropTable('users');
     }
     

   • Run rollbacks with:

     php bin/console effiana:migration:rollback
     

Integration Tips

1. Versioning Strategy

   • Use semantic versioning (e.g., 20240101000000) for migrations to ensure chronological ordering.
   • Avoid gaps in version numbers to prevent migration conflicts.

2. Environment-Specific Migrations

   • Place environment-specific migrations in subfolders (e.g., Migrations\Schema/production/20240101000000/).
   • Use a custom command to filter migrations by environment.

3. Testing Migrations

   • Test migrations in a staging environment or via Dockerized databases before production.
   • Use PHPUnit to assert schema changes:

     $this->assertDatabaseHas('users', ['name' => 'Admin']);
     

4. Combining with Doctrine Migrations

   • If using Doctrine, avoid duplication: Use this bundle for cross-database schema changes and Doctrine for entity-driven migrations.

Gotchas and Tips

Pitfalls

1. Version Number Conflicts

   • Issue: Duplicate version numbers across bundles or migrations.
   • Fix: Use a unique prefix (e.g., 20240101000000_app_) or namespace migrations by bundle.

2. Database-Specific Syntax

   • Issue: Raw SQL queries may fail on unsupported databases.
   • Fix: Use DBAL’s Schema object for portability; wrap custom SQL in try-catch blocks.

3. Missing down() Method

   • Issue: Rollbacks fail if down() is not implemented.
   • Fix: Always define down() for critical migrations or document why it’s omitted.

4. Fixture Dependencies

   • Issue: Fixtures may fail if referenced tables don’t exist.
   • Fix: Order fixtures by dependency (e.g., seed roles before users).

5. Transaction Failures

   • Issue: Large migrations may time out or lock tables.
   • Fix: Break migrations into smaller batches or run during low-traffic periods.

Debugging

1. Dry Runs Use --dry-run to preview changes:

   php bin/console effiana:migration:migrate --dry-run
   

2. Logging Enable verbose output for debugging:

   php bin/console effiana:migration:migrate -v
   

3. Schema Dumps Export the current schema for comparison:

   php bin/console doctrine:schema:dump-sql > schema.sql
   

Extension Points

1. Custom Migration Directories Override the default migration path in config/packages/effiana_migration.yaml:

   effiana_migration:
       schema_migrations_directory: '%kernel.project_dir%/custom/migrations'
   

2. Event Listeners Subscribe to migration events (e.g., MigrationEvents::PRE_MIGRATE) to add pre/post hooks:

   use Effiana\MigrationBundle\Event\MigrationEvents;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class MigrationSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               MigrationEvents::PRE_MIGRATE => 'onPreMigrate',
           ];
       }
   
       public function onPreMigrate($event)
       {
           // Add logic here (e.g., backup database)
       }
   }
   

3. Custom Query Bag Extend QueryBag to add database-specific methods:

   namespace App\Migration;
   
   use Effiana\MigrationBundle\Migration\QueryBag;
   
   class CustomQueryBag extends QueryBag
   {
       public function addPostgresExtension(string $extension): void
       {
           $this->addPostQuery("CREATE EXTENSION IF NOT EXISTS {$extension};");
       }
   }
   

   Bind it in your migration:

   $queries = new CustomQueryBag();
   $queries->addPostgresExtension('uuid-ossp');
   

Configuration Quirks

1. Autoloading Migrations Ensure migrations are autoloaded by Composer. Add this to composer.json:

   "autoload": {
       "psr-4": {
           "App\\Migrations\\": "Migrations/"
       }
   }
   

2. Case-Sensitive Paths

   • Issue: Linux/macOS vs. Windows path cases may cause failures.
   • Fix: Use forward slashes consistently in migration paths.

3. Doctrine vs. DBAL Conflicts

   • Issue: Mixing Doctrine and DBAL migrations may lead to schema drift.
   • Fix: Stick to one tool per project or use a migration manager to coordinate both.