Laravel Superseeder Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require spatie/laravel-superseeder
   

   Publish the config file (optional):

   php artisan vendor:publish --provider="Spatie\SuperSeeder\SuperSeederServiceProvider" --tag="superseeder-config"
   

2. First Use Case: Basic Seeding Define a seeder class extending Spatie\SuperSeeder\SuperSeeder:

   use Spatie\SuperSeeder\SuperSeeder;
   use App\Models\User;
   
   class UserSeeder extends SuperSeeder
   {
       public function run()
       {
           $this->seed(User::class, [
               'name' => 'John Doe',
               'email' => 'john@example.com',
               'password' => bcrypt('password'),
           ]);
       }
   }
   

   Run it via Artisan:

   php artisan db:seed --class=UserSeeder
   

3. Where to Look First

   • Config File: config/superseeder.php (for default settings like batch size, retries).
   • Documentation: GitHub README for advanced features (e.g., relationships, factories).
   • Examples: Check the tests/ directory in the package for real-world usage patterns.

Implementation Patterns

1. Seeding with Relationships

Use with() to define relationships dynamically:

$this->seed(User::class, [
    'name' => 'Jane Doe',
])
->with('posts', [
    ['title' => 'First Post', 'body' => 'Hello World'],
    ['title' => 'Second Post', 'body' => 'Laravel is awesome'],
]);

2. Batch Processing

For large datasets, leverage chunking:

$this->seedMany(User::class, $users, 100); // Batch size of 100

3. Factories Integration

Combine with Laravel’s factories for reusable data:

$this->seed(User::class, [
    'name' => 'Factory User',
])->createUsing(User::factory());

4. Conditional Seeding

Use when() to conditionally seed records:

$this->seed(User::class, [
    'name' => 'Admin',
    'role' => 'admin',
])->when(fn ($user) => $user->role === 'admin', function ($user) {
    $user->posts()->create(['title' => 'Admin Post']);
});

5. Workflow: Full Project Setup

1. Define Seeders: Create modular seeders (e.g., UserSeeder, PostSeeder).
2. Compose Data: Use arrays, JSON files, or API responses as input.
3. Run in Stages:

   php artisan db:seed --class=UserSeeder
   php artisan db:seed --class=PostSeeder
   

4. Automate: Add to DatabaseSeeder for one-command execution:

   public function run()
   {
       $this->call([
           UserSeeder::class,
           PostSeeder::class,
       ]);
   }
   

6. Integration with Testing

Seed test data in phpunit.xml:

<env name="DB_SEEDER_CLASS" value="TestSeeder"/>

Gotchas and Tips

Pitfalls

1. Foreign Key Constraints

   • Seed parent models (e.g., User) before child models (e.g., Post) to avoid SQLSTATE[23000] errors.
   • Use transactions for atomic operations:

     DB::transaction(function () {
         $this->seed(User::class, [...]);
         $this->seed(Post::class, [...]);
     });
     

2. Duplicate Data

   • Use unique() to enforce uniqueness (e.g., emails):

     $this->seed(User::class, [
         'email' => 'unique@example.com',
     ])->unique('email');
     

   • Tip: Combine with updateOrCreate for idempotent seeding:

     User::updateOrCreate(['email' => 'john@example.com'], [
         'name' => 'John Doe',
     ]);
     

3. Performance Bottlenecks

   • Batch Size: Default is 100; adjust in config/superseeder.php for memory constraints.
   • Indexes: Disable indexes temporarily for bulk inserts:

     DB::statement('ALTER TABLE users DISABLE TRIGGER ALL');
     // Seed here
     DB::statement('ALTER TABLE users ENABLE TRIGGER ALL');
     

4. Timestamps

   • By default, created_at/updated_at are auto-filled. Disable with:

     $this->seed(User::class, [...])->ignoreTimestamps();
     

Debugging Tips

1. Log Seeding Progress Use Laravel’s logging:

   $this->seed(User::class, [...])->log();
   

   Check storage/logs/laravel.log.

2. Validate Data Use validate() to ensure data integrity:

   $this->seed(User::class, [
       'email' => 'invalid-email',
   ])->validate();
   

3. Rollback Failed Seeders Wrap in a transaction with rollback:

   DB::transaction(function () {
       try {
           $this->seed(User::class, [...]);
       } catch (\Exception $e) {
           DB::rollBack();
           throw $e;
       }
   });
   

Extension Points

1. Custom Seeders Extend SuperSeeder to add domain-specific logic:

   class CustomSeeder extends SuperSeeder
   {
       protected function afterSeed($model)
       {
           // Post-processing (e.g., send welcome email)
       }
   }
   

2. Data Sources

   • CSV/JSON: Load from files:

     $data = json_decode(file_get_contents('data/users.json'), true);
     $this->seedMany(User::class, $data);
     

   • APIs: Fetch data dynamically:

     $response = Http::get('https://api.example.com/users');
     $this->seedMany(User::class, $response->json());
     

3. Event Listeners Trigger events after seeding:

   event(new UsersSeeded($users));
   

4. Testing Helpers Create a TestSeeder to reset state:

   class TestSeeder extends SuperSeeder
   {
       public function run()
       {
           $this->truncateAll();
           $this->seed(User::class, [...]);
       }
   }