Composer Bundle Migration Laravel Package

Getting Started

Minimal Setup

1. Install the package in your root Laravel project:

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

2. Add scripts to composer.json under scripts:

   "scripts": {
       "post-install-cmd": [
           "ComposerBundleMigration\\Composer\\Migrations::synchronizeMigrations"
       ],
       "post-update-cmd": [
           "ComposerBundleMigration\\Composer\\Migrations::synchronizeMigrations"
       ]
   }
   

3. Run migrations sync (optional, but recommended after first install):

   composer update
   

   This copies all migrations from installed bundles to your root project’s app/DoctrineMigrations (default).

First Use Case

• Problem: You’re using Doctrine migrations from vendor bundles (e.g., FOSUserBundle), but want them in your project for version control and customization.
• Solution: After installation, run composer update to sync migrations to your root project. Now you can:
  • Modify migrations without touching vendor code.
  • Commit migrations to Git.
  • Run php bin/console doctrine:migrations:execute locally.

Implementation Patterns

Workflow Integration

1. Post-Install/Update Hooks:

   • Automatically sync migrations on composer install/update via post-install-cmd/post-update-cmd.
   • Avoid manual copying; keep migrations in sync with dependencies.

2. Custom Migration Directories:

   • Override the default app/DoctrineMigrations by adding to composer.json:

     "extra": {
         "appMigrationsDir": "database/migrations/doctrine"
     }
     

   • Useful for projects with non-standard directory structures.

3. Bundle-Specific Source Paths:

   • Some bundles store migrations in non-standard locations (e.g., Migrations/ instead of Resources/migrations).
   • Configure per-bundle in their composer.json:

     "extra": {
         "migration-source": "Migrations"
     }
     

4. Laravel-Specific Adaptations:

   • Combine with Laravel’s migrate command by ensuring your doctrine/orm migrations are in the synced directory.
   • Example php artisan alias in ~/.bashrc:

     alias migrate-doctrine="php bin/console doctrine:migrations:execute --up"
     

5. CI/CD Pipelines:

   • Add composer update to your CI workflow to ensure migrations are synced before testing.
   • Example GitHub Actions step:

     - run: composer update --no-interaction
     

Common Patterns

• Sync Before Development: Run composer update in a fresh clone to pull migrations from all bundles.
• Exclude Specific Bundles: If a bundle’s migrations shouldn’t be synced, exclude it by modifying the package’s composer.json or overriding the sync logic (see Extension Points).
• Post-Sync Validation: Add a script to verify synced migrations (e.g., check for duplicates or invalid YAML):

  "scripts": {
      "post-migrate-sync": [
          "@post-update-cmd",
          "php scripts/validate-migrations.php"
      ]
  }
  

Gotchas and Tips

Pitfalls

1. Race Conditions:

   • Running composer update concurrently with other processes (e.g., php artisan migrate) may cause file lock issues.
   • Fix: Run migrations sync in a dedicated step or use --no-scripts for updates, then manually trigger sync.

2. Duplicate Migrations:

   • If a bundle’s migrations are synced multiple times (e.g., due to nested dependencies), duplicates may appear.
   • Fix: Use git status to detect duplicates or add a pre-sync cleanup script:

     find app/DoctrineMigrations -name "*.php" -type f -exec md5sum {} \; | sort | uniq -w32 -D
     

3. Permission Issues:

   • The sync script may fail if the target directory isn’t writable.
   • Fix: Ensure storage/ and app/ have correct permissions (e.g., chmod -R 775 storage app).

4. Non-Standard Bundle Structures:

   • Some bundles (e.g., legacy or custom) may store migrations in unexpected locations.
   • Fix: Override migration-source in the bundle’s composer.json or extend the sync logic (see below).

5. Laravel’s migrate Command Conflicts:

   • If you’re using both Laravel’s migrations and Doctrine’s doctrine:migrations, ensure paths don’t clash.
   • Fix: Use separate directories (e.g., database/migrations for Laravel, app/DoctrineMigrations for Doctrine).

Debugging

• Verbose Output: Enable debug mode by passing an environment variable:

  COMPOSER_BUNDLE_MIGRATION_DEBUG=1 composer update
  

• Dry Run: Inspect what would be synced without copying:

  COMPOSER_BUNDLE_MIGRATION_DRY_RUN=1 composer update
  

• Log File: Check var/log/composer-bundle-migration.log (if configured) for sync details.

Tips

1. Extension Points:

   • Override the sync logic by extending the Migrations class:

     // In a custom Composer plugin
     use ComposerBundleMigration\Composer\Migrations as BaseMigrations;
     
     class CustomMigrations extends BaseMigrations {
         protected function getSourcePaths(): array {
             $paths = parent::getSourcePaths();
             $paths[] = 'custom/path'; // Add extra directories
             return $paths;
         }
     }
     

   • Register the custom class in composer.json:

     "scripts": {
         "post-update-cmd": [
             "CustomMigrations::synchronizeMigrations"
         ]
     }
     

2. Git Ignore:

   • Add synced migrations to .gitignore if they’re auto-generated (e.g., by doctrine/orm):

     app/DoctrineMigrations/*_Y-m-d_His.php
     

3. Backup Synced Migrations:

   • Create a backup before syncing to avoid losing custom changes:

     cp -r app/DoctrineMigrations app/DoctrineMigrations.bak
     composer update
     

4. Symfony vs. Laravel:

   • If your project is Symfony + Laravel hybrid, ensure the Doctrine bundle is configured to use the synced directory:

     # config/packages/doctrine_migrations.yaml
     doctrine_migrations:
         migrations_paths:
             'ChampsLibres\ComposerBundleMigration': '%appMigrationsDir%'
     

5. Performance:

   • For large projects, sync only changed bundles by modifying the script to check composer.json diffs:

     // In a custom plugin
     public function synchronizeMigrations() {
         $updatedPackages = $this->getUpdatedPackages();
         if (empty($updatedPackages)) return;
         parent::synchronizeMigrations();
     }