Third Party Migrations Laravel Package

Technical Evaluation

Architecture Fit

• Modularity Alignment: The package aligns well with Laravel’s modular architecture, particularly for packages requiring database schema migrations (e.g., plugins, add-ons, or third-party integrations). It abstracts migration ownership by package, reducing conflicts in shared environments.
• Doctrine ORM Compatibility: Leverages Laravel’s built-in Doctrine Migrations system, ensuring seamless integration with Eloquent and database-agnostic operations (MySQL, PostgreSQL, SQLite).
• Schema Versioning: Introduces a package_schema_version table to track per-package schema states, which is critical for multi-tenant or multi-package Laravel applications where migrations must be isolated.

Integration Feasibility

• Low Friction: Requires minimal changes to existing Laravel migration workflows. Third-party packages can define migrations without modifying core application logic.
• Symfony Bundle Adaptability: While designed for Symfony, the core logic (migration registration, version tracking) is framework-agnostic. Laravel’s service container and event system can replicate the bundle’s functionality with minor adjustments (e.g., custom service providers).
• Migration Types: Supports two migration patterns:
  1. Installation Migrations: Full schema definitions (e.g., Version0000_Install).
  2. Update Migrations: Incremental changes (e.g., Version0001_AddColumn). This mirrors Laravel’s native migration conventions, easing adoption.

Technical Risk

• Laravel-Specific Gaps:
  • Symfony’s bundles.php configuration lacks a direct Laravel equivalent. A custom service provider or package bootstrap would be needed to register the bundle’s components (e.g., migration loader, version tracker).
  • Laravel’s Artisan command structure may require wrapping or extending existing migrate commands to support package-specific version checks.
• Database Schema Assumptions:
  • The package_schema_version table must be manually created or migrated. Laravel’s migrations table is separate, risking potential conflicts if not synchronized.
  • No built-in rollback logic for package-specific migrations; requires explicit down() methods in migrations.
• Testing Overhead:
  • Package migrations must be tested in isolation to avoid versioning conflicts. Laravel’s testing tools (e.g., MigrateFresh) may need customization to validate package-specific schema states.

Key Questions

1. Migration Isolation:

   • How will conflicts be handled if two third-party packages define migrations for the same table/column?
   • Does Laravel’s Schema::defaultStringLength() or other global settings need to be preserved per-package?

2. Versioning Strategy:

   • Should package versions (e.g., Version0001) align with Composer package versions or follow a custom schema?
   • How will downgrades (e.g., php artisan migrate:rollback) be managed for package-specific migrations?

3. Performance:

   • What impact will the package_schema_version table have on query performance in high-transaction environments?
   • Are there plans to optimize version checks for large-scale deployments?

4. Tooling Integration:

   • Can this package integrate with Laravel Forge/Sail/Envoyer for zero-downtime deployments?
   • How will it interact with Laravel’s migrate:status or migrate:fresh commands?

5. Maintenance:

   • Who owns the package_schema_version table in a multi-developer environment?
   • How will schema changes be communicated between package maintainers and application developers?

Integration Approach

Stack Fit

• Laravel Compatibility:
  • Core: Replace Symfony bundle with a Laravel service provider to register:
    • Migration loader (extends Doctrine\Migrations\Configuration\Migration\PhpFile).
    • Version tracker (replaces package_schema_version table logic).
    • Artisan commands (e.g., migrate:package to run migrations for a specific package).
  • Dependencies: Requires Laravel 8+ (for Symfony components compatibility) and Doctrine Migrations (doctrine/dbal).
• Alternative: Use Laravel’s Schema::create() within package migrations to avoid Doctrine overhead, but lose cross-DB compatibility.

Migration Path

1. Phase 1: Core Integration

   • Publish the package_schema_version table via a Laravel migration (e.g., create_package_schema_versions_table.php).
   • Create a service provider (ThirdPartyMigrationsServiceProvider) to:
     • Register the version tracker as a singleton.
     • Extend the migrate command to filter migrations by package.
   • Example:

     // app/Providers/ThirdPartyMigrationsServiceProvider.php
     public function register() {
         $this->app->singleton(VersionTracker::class, function () {
             return new VersionTracker(new Connection($this->app['db']));
         });
     }
     

2. Phase 2: Package Adoption

   • Third-party packages define migrations in Resources/migrations/ (e.g., Version0001_AddUserTable.php).
   • Use a trait or base class to standardize migration naming and versioning:

     // src/Traits/ThirdPartyMigration.php
     abstract class ThirdPartyMigration extends Migration {
         protected string $packageName;
         protected int $version;
     
         public function __construct(string $packageName, int $version) {
             $this->packageName = $packageName;
             $this->version = $version;
         }
     }
     

3. Phase 3: Artisan Extensions

   • Add commands:
     • migrate:package {package}: Run migrations for a specific package.
     • migrate:package:status: Show version status per package.
   • Example command:

     // app/Console/Commands/MigratePackage.php
     protected function handle() {
         $package = $this->argument('package');
         $migrations = $this->getPackageMigrations($package);
         // Execute migrations...
     }
     

Compatibility

• Doctrine Migrations: Fully compatible; no changes needed to existing migration files.
• Laravel Events: Can emit events (e.g., package.migration.running) for observability.
• Testing: Use Laravel’s MigrateFresh with a custom seed to reset package_schema_version:

  // tests/TestCase.php
  protected function setUp(): void {
      parent::setUp();
      $this->artisan('migrate:fresh');
      $this->artisan('db:seed', ['--class' => 'PackageSchemaVersionsSeeder']);
  }
  

Sequencing

1. Initial Setup:
   • Run core Laravel migrations (php artisan migrate).
   • Seed package_schema_version with initial package versions (e.g., 0).
2. Package Installation:
   • Install third-party packages via Composer.
   • Run php artisan migrate:package {vendor/package} to apply migrations.
3. Updates:
   • New package versions trigger Version{next}_Update.php migrations.
   • Use php artisan migrate:package {package} --step=1 for incremental updates.

Operational Impact

Maintenance

• Schema Drift Risk:
  • Manual synchronization required if package_schema_version and migrations tables diverge. Mitigate with:
    • Database backups before major updates.
    • CI checks for schema consistency (e.g., php artisan migrate:status + custom validation).
• Package Dependency Management:
  • Composer scripts can automate migration runs post-install:

    // composer.json
    "scripts": {
      "post-install-cmd": [
        "php artisan migrate:package vendor/package"
      ]
    }
    

• Deprecation:
  • Plan for migration of packages away from this system if Laravel introduces native support (e.g., via migrate:package in Laravel 11+).

Support

• Debugging:
  • Log package-specific migration execution to storage/logs/laravel.log:

    // In ThirdPartyMigration class
    public function up() {
        Log::info("Running {$this->packageName} migration {$this->version}");
        // Migration logic...
    }
    

  • Add a migrate:package:debug command to show SQL queries for a package’s migrations.
• Rollback Strategy:
  • Document rollback procedures for each package (e.g., "To downgrade vendor/package from v2.0 to v1.0, run php artisan migrate:package vendor/package down --step=1").
  • Consider a migrate:package:rollback command with confirmation prompts.

Scaling

• Performance:
  • Version Lookups: Add indexes to package_schema_version:

    Schema::table('package_schema_version', function (Blueprint $table) {
        $table->index(['package_name', 'version']);
    });
    

  • Batch Migrations: For large schemas, split migrations into smaller batches (e.g., Version0001_Part1, Version0001_Part2).
• Concurrency:
  • Use database transactions for atomic package migration runs:

    DB::transaction(function () {
        $this->versionTracker->updateVersion($package, $version);
        // Run migration...
    });