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.
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 theOrm, 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.