Entity Migrator Laravel Package

Technical Evaluation

Architecture Fit

• Schema/Data Migration Synergy: The package excels at complex data transformations (e.g., splitting tables, column renaming with data mapping) where Laravel’s native migrations fall short. Ideal for legacy modernization or microservice decomposition in Laravel monoliths.
• Symfony-Laravel Hybrid Potential: While Laravel lacks native async migration support, this package’s Messenger/Workflow integration aligns with Laravel’s queue system and event-driven architecture, enabling non-blocking schema changes (critical for SaaS or financial apps).
• Doctrine vs. Illuminate Database: The core tension is Doctrine DBAL vs. Laravel’s Eloquent/Schema. The package is not a drop-in replacement but a supplemental tool for scenarios requiring atomic, retryable, or workflow-orchestrated migrations.

Integration Feasibility

• Symfony Messenger Bridge:
  • Laravel’s spatie/laravel-messenger can act as a compatibility layer, but message serialization (e.g., Doctrine entities vs. Eloquent models) may require custom handlers.
  • Risk: Symfony’s MessageBus expects PSR-15 messages; Laravel’s queues use serializable payloads. A message adapter (e.g., SymfonyMessageToLaravelQueue) is needed.
• Doctrine DBAL Adapter:
  • Laravel’s Schema builder and DBAL can coexist if migrations are partitioned (e.g., use Schema for DDL, DBAL for DML via the package).
  • Challenge: Laravel’s Schema migrations lock the database during execution, while this package supports concurrent, locked operations—conflicts may arise in mixed workflows.
• Workflow Component:
  • Laravel’s state machines (e.g., spatie/laravel-state-machines) could replace Symfony’s Workflow, but transition hooks (e.g., "migration approved") would need custom event listeners.

Technical Risk

• Highest Risk: Hybrid Architecture Complexity
  • Mixing Laravel’s Schema migrations with Symfony’s EntityMigrator risks inconsistent migration states (e.g., schema changes applied but data transformations failed).
  • Mitigation: Enforce a single migration system (either all Schema or all EntityMigrator) per project phase.
• Medium Risk: Doctrine Dependency
  • Laravel apps using only Eloquent may need to add Doctrine DBAL, increasing bundle size and complexity.
  • Mitigation: Use the package only for data migrations, keeping schema changes in Laravel’s Schema.
• Low Risk: Rollback Gaps
  • The package lacks native rollback support for data changes. Laravel’s down() methods are schema-focused.
  • Mitigation: Implement custom rollback logic using the package’s Migration::down() or database backups for critical data.

Key Questions

1. Migration Strategy:

   • Are we replacing Laravel migrations entirely or supplementing them for complex data changes?
   • Example: Use EntityMigrator for legacy data cleanup but Schema for new feature migrations.

2. Symfony Ecosystem Adoption:

   • Is the team open to adding Symfony Messenger/Workflow to the stack, or should we build a Laravel-native alternative (e.g., using spatie/laravel-messenger + custom workflow logic)?

3. Data Consistency:

   • How will we handle schema changes (Laravel Schema) vs. data transformations (EntityMigrator) in the same migration?
   • Example: Avoid running Schema::table() and EntityMigrator in parallel on the same table.

4. Performance Tradeoffs:

   • Will async migrations (via Messenger) introduce unpredictable latency for critical schema changes?
   • Example: A financial app may need synchronous, locked migrations for auditability.

5. Testing Strategy:

   • How will we test workflow-based migrations (e.g., "migrate in batches with approvals")?
   • Example: Use Laravel’s Queue::fake() + Symfony’s WorkflowTester.

Integration Approach

Stack Fit

Migration Path

1. Phase 1: Schema-Only Migrations (Low Risk)

   • Use Laravel’s Schema for all DDL changes (no EntityMigrator).
   • Goal: Baseline migration workflow.

2. Phase 2: Data Migrations (Medium Risk)

   • Introduce EntityMigrator for data-only changes (e.g., column updates, row transformations).
   • Implementation:
     • Add doctrine/dbal to composer.json.
     • Create a hybrid migration class:

       use Draw\EntityMigrator\Migration;
       use Illuminate\Database\Schema\Blueprint;
       
       class UserDataMigration extends Migration
       {
           public function up()
           {
               // Schema changes (Laravel)
               Schema::table('users', function (Blueprint $table) {
                   $table->string('new_column')->nullable();
               });
       
               // Data changes (EntityMigrator)
               $this->updateField('users', 'old_column', 'new_column');
           }
       }
       

   • Tooling: Use spatie/laravel-messenger to bridge Symfony Messenger.

3. Phase 3: Workflow Migrations (High Risk)

   • Enable async, multi-step migrations (e.g., "validate → migrate → notify").
   • Implementation:
     • Set up Symfony Workflow with Laravel events:

       // app/Providers/EventServiceProvider.php
       protected $listen = [
           'workflow.transition' => [
               \App\Listeners\LogMigrationStep::class,
           ],
       ];
       

     • Use Laravel’s Queues for async steps:

       $this->bus->dispatch(new MigrateDataMessage($entity, $data));
       

4. Phase 4: Full Replacement (Critical Risk)

   • Replace all Laravel migrations with EntityMigrator.
   • Prerequisite: Full Doctrine DBAL adoption and Symfony Messenger integration.
   • Use Case: Only justified for large-scale, long-term migration projects (e.g., monolith decomposition).

Compatibility

• Laravel 10/11: Compatible with Symfony 6.4+, but queue/messenger integrations may require custom glue code.
• Doctrine DBAL: Works, but schema changes should avoid mixing with Laravel’s Schema to prevent conflicts.
• Rollbacks: Not natively supported. Implement:
  • Schema rollbacks: Use Laravel’s down() methods.
  • Data rollbacks: Use EntityMigrator::down() or database transactions with manual undo logic.

Sequencing

1. Pre-Migration:

   • Audit existing migrations for complexity (target data-heavy migrations first).
   • Set up Doctrine DBAL and Symfony Messenger in a dedicated branch.

2. Migration Execution:

   • Order: Schema → Data → Workflow (never run schema/data in parallel).
   • Locking: Use Symfony’s Lock component to prevent concurrent migrations on the same table.

3. Post-Migration:

   • Validation: Run draw/tester to verify data integrity.
   • Monitoring: Log workflow transitions to Laravel Horizon or Sentry.

Operational Impact

Maintenance

• Pros:
  • Declarative: Migrations are versioned and testable (unlike ad-hoc SQL scripts).
  • Auditability: Workflow logs track every migration step (critical for compliance).
• Cons:
  • Symfony Dependency: Updates to symfony/messenger or workflow may break Laravel integrations.
  • Custom Boilerplate: Adapters (DBAL, Messenger) require ongoing maintenance.
  • Debugging: Workflow-based migrations are harder to debug than linear Schema