Files
dgarcia 2acf2cc099 feat(seeding): add the seeder concept with an idempotent runner
A seeder fills reference or bootstrap data - the permission catalogue, the
built-in roles, the first administrator. It is not a migration: it never
touches the schema, it runs on demand, and it must be safe to run twice.

- Seeder: the contract (name + run).
- AbstractSeeder: seedOnce() inserts only when the criteria match nothing and
  records inserted/skipped counts. It never overwrites a row a user edited.
- SeederRunner: runs an ordered batch inside one transaction, so a failing
  seeder leaves the database untouched. Supports running a named subset.
- SeederResult: per-seeder outcome for reporting.
- ConfigurationException::unknownSeeder() lists the registered names.

docs/SEEDING.md documents the contract and how to write one.
2026-11-15 13:30:54 -03:00

2.1 KiB

Seeder

A Seeder populates a table with reference or bootstrap rows: the permission catalogue, the built-in roles, the first administrator. It is not a migration: it runs on demand, it is idempotent, and it never changes the schema.

Contract

interface Seeder
{
    public function name(): string;

    public function run(Orm $orm): void;
}
  • name() is what you type on the command line and what the runner orders by. Keep it short and unique: permissions, roles, admin-user.
  • run() receives the Orm, so a seeder writes through repositories like any other consumer. It must be safe to run twice: an insert of an existing row is a no-op, not an error.
  • A seeder throws nothing it cannot explain. A failure stops the batch and is reported.

Runner

Camelia\Orm\Seeding\SeederRunner executes an ordered list of seeders inside one transaction:

$runner = new SeederRunner($orm, [new PermissionsSeeder(), new RolesSeeder(), new AdminSeeder()]);
$report = $runner->run();

Every seeder runs in the same transaction: either the whole batch applies or none of it does. The report tells you what happened per seeder.

Writing a seeder

Subclass AbstractSeeder to get idempotent helpers instead of hand-rolling findOrCreate calls:

final class PermissionsSeeder extends AbstractSeeder
{
    public function name(): string
    {
        return 'permissions';
    }

    public function run(Orm $orm): void
    {
        $repository = $orm->repository(PermissionModel::class);

        foreach (Permission::cases() as $permission) {
            $this->seedOnce($repository, ['code' => $permission->value], [
                'module' => $permission->module(),
                'action' => $permission->action(),
            ]);
        }
    }
}

seedOnce() inserts when the criteria match nothing and reports whether it did. It never updates an existing row, because a seeder that silently overwrites data the user edited is a footgun.

Ordering

Seeders run in the order you pass them. When a seeder depends on rows another one creates (roles need permissions), pass them in dependency order and let the transaction protect you.