Composer Bundle Migration Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The package addresses a common pain point in Symfony/Laravel ecosystems where Doctrine migrations are scattered across vendor bundles, complicating versioning, dependency management, and CI/CD pipelines. This aligns well with monorepo-like migration management in PHP projects.
• Symfony/Laravel Compatibility:
  • Symfony: Native fit (DoctrineMigrationsBundle is standard).
  • Laravel: Indirect fit (requires DoctrineMigrationsBundle or manual Doctrine DBAL setup; migrations are typically managed via php artisan migrate without bundles).
  • Risk: Laravel’s migration system is opinionated (e.g., database/migrations/), reducing immediate need but not eliminating use cases (e.g., multi-module projects with shared migrations).
• Key Tradeoffs:
  • Centralization vs. Decentralization: Moves migrations to root, improving traceability but potentially breaking modularity if bundles expect migrations to live in their own directories.
  • Vendor Lock-in: AGPL-3.0 license may restrict proprietary projects (check compliance).

Integration Feasibility

• Core Requirements:
  • Doctrine DBAL/MigrationsBundle: Mandatory for Symfony; optional but required for Laravel.
  • Composer Script Hooks: post-install-cmd/post-update-cmd are standard but may conflict with existing scripts (e.g., Laravel’s post-autoload-dump).
  • Directory Structure: Assumes app/DoctrineMigrations (Symfony default) or custom paths; Laravel’s database/migrations/ would need alignment.
• Technical Risk:
  • Migration Conflicts: Duplicate filenames between bundles/root may cause overwrites or merge failures.
  • CI/CD Impact: Scripts run during composer install/update, which may slow pipelines or fail if migrations are incomplete.
  • Backward Compatibility: Bundles relying on Resources/migrations may break if not updated to use the new location.

Key Questions

1. Project Scope:
   • Is this for a Symfony monolith or a Laravel multi-package setup? (Laravel may need custom adaptation.)
   • Are migrations shared across bundles or bundle-specific? (Shared migrations benefit most.)
2. Existing Workflow:
   • How are migrations currently managed? (Manual copies? Git submodules?)
   • Are there existing composer.json scripts that could conflict?
3. License Compliance:
   • Can the project adopt AGPL-3.0, or is a custom fork needed?
4. Testing:
   • How will migration conflicts (e.g., same filename) be handled?
   • Are there rollback mechanisms if synchronization fails?
5. Performance:
   • What’s the expected scale (e.g., 100+ migrations)? Will synchronization be slow?

Integration Approach

Stack Fit

Migration Path

1. Assessment Phase:
   • Audit existing migration locations (bundles vs. root).
   • Identify conflicts (duplicate filenames, unsupported bundles).
   • Validate Doctrine setup (Symfony: MigrationsBundle; Laravel: DBAL + custom config).
2. Pilot Integration:
   • Install package in a staging environment:

     composer require champs-libres/composer-bundle-migration ~1.0
     

   • Configure composer.json:

     "scripts": {
         "post-install-cmd": ["ComposerBundleMigration\\Composer\\Migrations::synchronizeMigrations"],
         "post-update-cmd": ["ComposerBundleMigration\\Composer\\Migrations::synchronizeMigrations"]
     },
     "extra": {
         "appMigrationsDir": "database/migrations"  // Laravel example
     }
     

   • Test with a subset of bundles to validate synchronization.
3. Full Rollout:
   • Update all bundles with migration-source config if needed.
   • Replace manual migration copies with the automated script.
   • Update CI/CD to handle potential synchronization failures (e.g., abort pipeline on errors).

Compatibility

• Symfony:
  • Works out-of-the-box with DoctrineMigrationsBundle.
  • May require bundle updates to avoid hardcoded migration paths.
• Laravel:
  • Requires:
    • Doctrine DBAL (doctrine/dbal).
    • Custom migration directory config (e.g., database/migrations).
    • Potential Laravel-specific script wrapper to avoid Composer hook conflicts.
• Conflicts:
  • Filename Collisions: Prioritize root migrations or implement merge strategies.
  • Bundle Assumptions: Some bundles may expect migrations in Resources/migrations; these must be updated.

Sequencing

1. Pre-Migration:
   • Backup all existing migrations.
   • Document current migration workflows.
2. Synchronization:
   • Run composer update to trigger initial sync.
   • Verify migrations exist in the target directory.
3. Post-Migration:
   • Update bundle documentation to reflect new migration paths.
   • Train team on the new workflow (e.g., "migrations now live in database/migrations").
4. Ongoing:
   • Monitor synchronization during composer install/update.
   • Review migration conflicts in pull requests.

Operational Impact

Maintenance

• Pros:
  • Single Source of Truth: Migrations centralized in root reduce "where is this migration?" questions.
  • Atomic Updates: Changes to migrations are versioned with the root package.
• Cons:
  • Dependency on Composer: Synchronization tied to composer install/update; manual runs may be needed.
  • Bundle Maintenance: Bundles must be updated to avoid hardcoded paths.
• Tasks:
  • Periodically audit appMigrationsDir for stale files.
  • Update migration-source configs if bundle migration paths change.

Support

• Debugging:
  • Failed Synchronization: Check Composer logs for errors (e.g., permission issues, missing directories).
  • Missing Migrations: Verify migration-source configs in dependent bundles.
• Common Issues:
  • Permission Errors: Ensure web server/user has write access to appMigrationsDir.
  • Doctrine Errors: Migrations may fail if DBAL is misconfigured (e.g., wrong DSN).
• Documentation:
  • Add a CONTRIBUTING.md section on migration management.
  • Document the migration-source config for bundle maintainers.

Scaling

• Performance:
  • Synchronization Time: Linear with number of migrations/bundles. Test with composer --profile to measure impact.
  • CI/CD: Add a composer validate-migrations script to fail fast if sync fails.
• Large Projects:
  • Consider parallelizing sync for monorepos (custom script extension).
  • Use Composer plugins to optimize post-install hooks.

Failure Modes

Ramp-Up

• Onboarding:
  • Developers: Train on new migration directory and Composer hooks.
  • Bundle Maintainers: Document migration-source config requirements.
• Training:
  • Workshop: "Managing Migrations in a Monorepo" covering:
    • Why centralize migrations.
    • How to configure migration-source.
    • Debugging sync issues.
• Tools:
  • Add a pre-commit hook to lint migration files (e.g., PHPStan for Doctrine annotations).
  • Create a dashboard (e.g., custom script) to visualize migration dependencies.