Superseeder Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require riftweb/superseeder
   php artisan migrate
   

   • Runs the seeder_executions table migration automatically.

2. First Trackable Seeder:

   php artisan make:superseeder FirstSeeder
   

   • Generates a seeder with TrackableSeed trait pre-included.

3. Basic Usage:

   // Database/Seeders/FirstSeeder.php
   public function run()
   {
       // Your seeding logic here
       DB::table('users')->insert([...]);
   }
   

   Run via:

   php artisan db:seed --class=FirstSeeder
   

First Use Case

• Production-safe seeding: Run a seeder once, then track its execution to prevent duplicates.

  php artisan db:seed --class=FirstSeeder --force  # Only works if not previously run
  

Implementation Patterns

Core Workflows

1. Tracked Seeding:

   // Automatically tracked via trait
   class UsersSeeder extends Seeder {
       use TrackableSeed;
       // ...
   }
   

   • Execution logged in seeder_executions table.

2. Batch Management:

   php artisan db:seed --class=UserSeeder,RoleSeeder,PermissionSeeder
   

   • Runs all seeders as a single transaction (atomic rollback if any fail).

3. Rollbacks:

   php artisan db:rollback --class=UsersSeeder
   

   • Reverses the seeder’s run() logic (requires manual rollback() method).

Integration Tips

• Custom Rollback Logic:

  public function rollback()
  {
      DB::table('users')->where('created_at', '>', now()->subDays(7))->delete();
  }
  

• Conditional Execution:

  public function shouldRun()
  {
      return User::count() === 0;
  }
  

• Bypass Mode (for emergencies):

  php artisan db:seed --class=UsersSeeder --bypass
  

  • Skips execution tracking (use sparingly).

Advanced Patterns

• Dependency Management:

  protected $dependencies = ['RolesSeeder', 'PermissionsSeeder'];
  

  • Ensures seeders run in order.

• Environment-Specific Seeders:

  public function shouldRun()
  {
      return app()->environment('local');
  }
  

Gotchas and Tips

Pitfalls

1. Rollback Limitations:

   • Rollbacks do not undo database transactions by default. Implement rollback() manually.
   • Tip: Use Laravel’s DB::transaction() in run() for atomicity.

2. Duplicate Executions:

   • The package prevents duplicates by default. Force runs with --force (use cautiously in production).

3. Missing seeder_executions Table:

   • Forgetting to run php artisan migrate will cause TrackableSeed to fail silently.
   • Fix: Run migrations before seeding.

4. Batch Failures:

   • If one seeder in a batch fails, the entire batch rolls back. Test batches locally first.

Debugging

• Check Execution Logs:

  SELECT * FROM seeder_executions ORDER BY created_at DESC;
  

• Enable Debug Mode:

  SUPERSEEDER_DEBUG=true
  

  • Logs detailed execution steps to storage/logs/laravel.log.

Extension Points

1. Custom Execution Table:

   • Override the table name in config/superseeder.php:

     'table' => 'custom_seeder_logs',
     

2. Event Hooks:

   • Listen for SuperSeeder.Ran or SuperSeeder.Rollback events:

     event(new SuperSeederRan($seeder, $batch));
     

3. Custom Generator:

   • Extend the make:superseeder command by publishing the template:

     php artisan vendor:publish --tag=superseeder-templates
     

Performance Tips

• Batch Seeders Efficiently:
  • Use chunking for large datasets:

    User::chunk(1000, function ($users) {
        // Process chunk
    });
    

• Avoid Long Transactions:
  • Break complex seeders into smaller batches to prevent timeouts.

Configuration Quirks

• Default Batch Size:
  • Set in config/superseeder.php:

    'batch_size' => 5, // Max seeders per transaction
    

• Bypass Mode:
  • Only works with --bypass flag; no tracking occurs. Use for one-off fixes.