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.
69 lines
2.1 KiB
Markdown
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.
|