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:
dgarcia committed 2026-11-15 13:30:54 -03:00
1 parent 02703f40ab
commit 2acf2cc099
7 files changed
+542

No files matched your search

+62
View File
@@ -0,0 +1,62 @@
<?php
declare(strict_types=1);
namespace Camelia\Orm\Seeding;
use Camelia\Orm\Model;
use Camelia\Orm\Repository;
/**
* Convenience base for seeders that insert reference rows.
*
* It offers the two things hand-written seeders get wrong: an idempotent insert and a count. It
* never updates an existing row, because a seeder that silently overwrites data a user edited is
* a footgun.
*
* @api
*/
abstract class AbstractSeeder implements Seeder
{
private int $inserted = 0;
private int $skipped = 0;
/**
* Inserts $values when $criteria match nothing, and leaves the row alone when they do.
*
* @template T of Model
* @param Repository<T> $repository
* @param array<string, mixed> $criteria
* @param array<string, mixed> $values merged into the criteria on insert
* @return T|null the new row, or null when it already existed
*/
final protected function seedOnce(
Repository $repository,
array $criteria,
array $values = [],
): ?Model {
if ($repository->findFirst($criteria) !== null) {
$this->skipped++;
return null;
}
$this->inserted++;
return $repository->create([...$criteria, ...$values]);
}
/**
* Rows inserted by the last run(). Used by the runner for its report.
*/
final public function inserted(): int
{
return $this->inserted;
}
final public function skipped(): int
{
return $this->skipped;
}
}
+29
View File
@@ -0,0 +1,29 @@
<?php
declare(strict_types=1);
namespace Camelia\Orm\Seeding;
use Camelia\Orm\Orm;
/**
* Fills reference or bootstrap data: the permission catalogue, the built-in roles, the first
* administrator.
*
* A seeder is not a migration. It never changes the schema, it runs on demand, and it must be safe
* to run twice: seeding an existing row is a no-op, not an error.
*
* @api
*/
interface Seeder
{
/**
* Stable, command-line friendly identifier. Also the sort key when order matters.
*/
public function name(): string;
/**
* Writes the rows. Called inside the runner's transaction.
*/
public function run(Orm $orm): void;
}
+51
View File
@@ -0,0 +1,51 @@
<?php
declare(strict_types=1);
namespace Camelia\Orm\Seeding;
/**
* What one seeder did, so the caller can report it without inspecting the database.
*
* @api
*/
final readonly class SeederResult
{
public function __construct(
public string $seeder,
public int $inserted,
public int $skipped,
public float $seconds,
public ?string $error = null,
) {}
public static function started(string $seeder): self
{
return new self($seeder, 0, 0, 0.0);
}
public function isSuccessful(): bool
{
return $this->error === null;
}
public function isNoOp(): bool
{
return $this->error === null && $this->inserted === 0;
}
public function summary(): string
{
if ($this->error !== null) {
return sprintf('%s: FAILED — %s', $this->seeder, $this->error);
}
return sprintf(
'%s: %d inserted, %d skipped (%.0f ms)',
$this->seeder,
$this->inserted,
$this->skipped,
$this->seconds * 1000,
);
}
}
+114
View File
@@ -0,0 +1,114 @@
<?php
declare(strict_types=1);
namespace Camelia\Orm\Seeding;
use Camelia\Orm\Exception\ConfigurationException;
use Camelia\Orm\Orm;
/**
* Runs an ordered list of seeders inside one transaction.
*
* Either the whole batch applies or none of it does: a seeder that fails leaves the database
* untouched, which is what makes re-running the command after a fix safe.
*
* Seeders that extend AbstractSeeder report how many rows they inserted; a plain Seeder reports
* zero and is still executed.
*
* @api
*/
final class SeederRunner
{
/** @var list<Seeder> */
private array $seeders = [];
public function __construct(
private readonly Orm $orm,
) {}
/**
* @param list<Seeder> $seeders
*/
public function addMany(array $seeders): self
{
foreach ($seeders as $seeder) {
$this->add($seeder);
}
return $this;
}
public function add(Seeder $seeder): self
{
$this->seeders[] = $seeder;
return $this;
}
/**
* Commands read this to offer `--only <name>` without running anything.
*
* @return list<string>
*/
public function names(): array
{
return array_map(static fn(Seeder $seeder): string => $seeder->name(), $this->seeders);
}
/**
* @param list<string> $only run just these, in the order given
* @return list<SeederResult>
*/
public function run(array $only = []): array
{
$selected = $this->select($only);
if ($selected === []) {
return [];
}
return $this->orm->transaction(fn(): array => array_map($this->execute(...), $selected));
}
/**
* @param list<string> $only
* @return list<Seeder>
*/
private function select(array $only): array
{
if ($only === []) {
return $this->seeders;
}
$unknown = array_values(array_diff($only, $this->names()));
if ($unknown !== []) {
throw ConfigurationException::unknownSeeder($unknown, $this->names());
}
$selected = [];
foreach ($only as $name) {
foreach ($this->seeders as $seeder) {
if ($seeder->name() === $name) {
$selected[] = $seeder;
}
}
}
return $selected;
}
private function execute(Seeder $seeder): SeederResult
{
$started = hrtime(true);
$seeder->run($this->orm);
$elapsed = (hrtime(true) - $started) / 1_000_000_000;
$inserted = $seeder instanceof AbstractSeeder ? $seeder->inserted() : 0;
$skipped = $seeder instanceof AbstractSeeder ? $seeder->skipped() : 0;
return new SeederResult($seeder->name(), $inserted, $skipped, $elapsed);
}
}