Snipe Migrations Laravel Package

Getting Started

• Install with composer require <vendor>/<package> (the v1.4.0 tag is the first with an explicit illuminate/support: ^8.0 constraint — confirm composer why-not resolves cleanly on an L8 app before upgrading production).
• Publish the package assets: php artisan vendor:publish --provider="<Vendor>\<Package>\<Package>ServiceProvider". You typically want the --tag=seeders (and --tag=config) groups separately so you can re-publish seeders without clobbering config.
• Run php artisan migrate then seed: php artisan db:seed --class="Database\\Seeders\\<Package>Seeder".
• Look first at: the published seeder files, not the package source. The L8 fix in v1.4.0 lives in the seeder namespace/run() signature, so the generated files are where regressions show up. Second place to look is your app's composer.json — verify "Database\\Seeders\\": "database/seeders/" exists in autoload.psr-4.
• First use case: seed reference/lookup data (countries, currencies, roles, statuses) in a fresh environment via php artisan migrate --seed, then confirm row counts match the package's documented totals.

Implementation Patterns

• Compose, don't copy. Keep the package seeder as the source of truth and invoke it from your Database\Seeders\DatabaseSeeder::run():

  public function run(): void
  {
      $this->call([
          \Database\Seeders\CountriesSeeder::class, // package-published
          \Database\Seeders\RolesSeeder::class,
      ]);
  }
  

  In Laravel 8 $this->call() accepts class-strings; prefer ::class constants over raw string paths so refactors don't silently no-op.
• Test fixtures. With RefreshDatabase, call $this->seed(\Database\Seeders\CountriesSeeder::class) in setUp() rather than running full migrate --seed — it's far faster and isolates the lookup tables your assertions depend on.
• Deployment pipeline. For idempotent production runs, seed after migrate --force in the same deploy step: php artisan migrate --force && php artisan db:seed --class="Database\\Seeders\\CountriesSeeder" --force. The --force flag is mandatory outside local.
• Wrap large seeds. For multi-thousand-row reference sets, wrap the seeder body in DB::transaction() or chunk inserts (array_chunk($rows, 500)) — the default seeder does one insert per row in older versions, which is a common timeout source.
• Foreign keys. If your app already references seeded IDs, seed parents before children and disable constraints around the block: Schema::disableForeignKeyConstraints() / enableForeignKeyConstraints() in a try/finally.
• Environment gating. Only register the seeding call in DatabaseSeeder when app()->environment(['local','staging','testing']), and rely on --class for production reference data.

Gotchas and Tips

• Laravel 8 moved seeders. Directories changed from database/seeds to database/seeders, and the default class from Database\Seeder to Database\Seeders\DatabaseSeeder. If you upgraded an app rather than installing fresh, previously published seeders sitting in database/seeds will no longer autoload and --class will throw Target class [...] does not exist. Re-publish, or move the files and update the namespace.
• Autoload dump required. After upgrading to v1.4.0 or moving seeder files, run composer dump-autoload. Stale autoload_classmap.php is the #1 cause of "seeder works on my machine" bugs.
• run() signature. Laravel 8 seeders use public function run(): void; the return type is optional but the void return is expected — a seeder returning a value or using the old Seeder base from the wrong namespace will fatal.
• Seeder not idempotent. Most reference-data seeders insert() rather than upsert()/updateOrInsert(). Re-running without migrate:fresh will duplicate rows or violate unique keys. Guard with a if (Model::count() > 0) return; check, or truncate first, depending on whether you need to pick up upstream data changes.
• Debugging silent failures. db:seed swallows a lot; add -vvv and check storage/logs/laravel.log. If rows are missing but no error appears, suspect a Model::unguard() missing and a mass-assignment Guarded exception being caught upstream.
• Extension points. Prefer subclassing the published seeder (class MyCountriesSeeder extends CountriesSeeder) and overriding run() when you need to add or filter rows — that keeps you able to re-publish on the next patch release without a merge conflict. If the package exposes a config array of tables/columns, set it in config/<package>.php rather than editing seeders.
• Version constraint. v1.4.0 adds L8 support but check whether the illuminate/* constraint is ^8.0 only or ^5.8|^6|^7|^8 — if the PR pinned it narrowly, an L7 app on a shared dependency will fail to resolve and you'll need to hold the previous tag.
• migrate:fresh --seed is safe for local resets, but never in a deploy script: it drops every table regardless of which seeder you scoped with --class.