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.
This commit is contained in:
1 parent
02703f40ab
commit
2acf2cc099
7 files changed
+542
No files matched your search
@@ -0,0 +1,68 @@
|
||||
# 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.
|
||||
Reference in new issue
Block a user