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

69 lines
2.1 KiB
Markdown

# 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
```php
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:
```php
$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:
```php
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.