Fregata Laravel Package

Getting Started

First Steps

1. Installation Add Fregata via Composer:

   composer require aymdev/fregata
   

   Publish the configuration (if needed):

   php artisan vendor:publish --provider="Aymdev\Fregata\FregataServiceProvider"
   

2. Basic Migration Define a migration in database/migrations/ (or a custom path):

   use Aymdev\Fregata\Migrations\Migration;
   
   class CreateUsersTable extends Migration
   {
       public function up()
       {
           $this->create('users', function ($table) {
               $table->id();
               $table->string('name');
               $table->timestamps();
           });
       }
   
       public function down()
       {
           $this->drop('users');
       }
   }
   

   Run migrations:

   php artisan fregata:migrate
   

3. First Use Case Use Fregata for schema-heavy projects where you need:

   • Atomic migrations (up/down methods).
   • Custom migration logic (e.g., data seeding, complex schema changes).
   • Rollback support without Laravel’s built-in migrator.

Implementation Patterns

1. Workflow Integration

• Seamless Laravel Integration Fregata works alongside Laravel’s migrations but offers more control for non-standard use cases (e.g., multi-database setups, custom storage).

  // In a custom command:
  $migrator = app(\Aymdev\Fregata\Migrator::class);
  $migrator->run();
  

• Batch Processing Process migrations in batches (e.g., for large-scale deployments):

  $migrator->batch(5)->run(); // Run 5 migrations at a time
  

• Conditional Migrations Skip or run migrations based on environment/config:

  if (config('app.env') === 'production') {
      $this->create('analytics_logs', function ($table) { ... });
  }
  

2. Advanced Patterns

• Custom Storage Backend Override the default migration storage (e.g., Redis, DynamoDB):

  $migrator->setStorage(new \Aymdev\Fregata\Storage\RedisStorage());
  

• Migration Dependencies Enforce order with dependsOn():

  class CreatePostsTable extends Migration
  {
      public function up()
      {
          $this->dependsOn('users'); // Runs after 'users' table exists
          $this->create('posts', function ($table) { ... });
      }
  }
  

• Post-Migration Hooks Execute logic after migration (e.g., cache warming, event dispatching):

  $migrator->after(function () {
      Cache::forget('schema_version');
  });
  

3. Testing Strategies

• Isolated Migration Tests Use Fregata’s Migrator in PHPUnit:

  public function test_migration()
  {
      $migrator = new \Aymdev\Fregata\Migrator();
      $migrator->run(new CreateUsersTable());
  
      $this->assertDatabaseHas('users', ['name' => 'Test']);
  }
  

• Rollback Testing Verify down() methods:

  $migrator->run(new CreateUsersTable());
  $migrator->rollback(new CreateUsersTable());
  $this->assertDatabaseMissing('users');
  

Gotchas and Tips

Common Pitfalls

1. Missing up()/down() Methods Fregata requires both methods (unlike Laravel’s optional down()). Omit either, and migrations fail silently.

2. Schema Locking Avoid running migrations concurrently—Fregata uses a lock file (storage/fregata.lock). Race conditions may cause timeouts.

3. Database-Specific Syntax Fregata’s query builder is not a drop-in for Laravel’s. Use raw SQL or the provided methods (e.g., $this->create(), $this->addColumn()).

4. Migration Order Guarantees Dependencies (dependsOn()) are not recursive. Manually chain migrations if needed:

   // Migration A depends on B and C
   $this->dependsOn('b');
   $this->dependsOn('c');
   

Debugging Tips

• Enable Verbose Logging

  php artisan fregata:migrate --verbose
  

  Or configure in config/fregata.php:

  'logging' => true,
  

• Inspect Migration Status Check the storage backend (default: database/migrations) for executed migrations:

  SELECT * FROM migrations;
  

• Rollback Failures If down() fails, manually reset the migration status:

  $migrator->reset();
  

Extension Points

1. Custom Query Builder Extend \Aymdev\Fregata\QueryBuilder for database-specific features:

   class CustomQueryBuilder extends \Aymdev\Fregata\QueryBuilder
   {
       public function addPostgresSpecificColumn($table, $column)
       {
           // Custom logic
       }
   }
   

   Bind it in the service provider:

   $this->app->bind(\Aymdev\Fregata\QueryBuilder::class, function () {
       return new CustomQueryBuilder();
   });
   

2. Event Listeners Listen to migration events (e.g., Migrating, Migrated):

   \Aymdev\Fregata\Events\Migrating::listen(function ($migration) {
       Log::info("Running {$migration->getName()}");
   });
   

3. Migration Factories Use factories for complex data seeding:

   $this->after(function () {
       \Aymdev\Fregata\Facades\Factory::create(\App\Models\User::class, 10);
   });