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
@@ -38,4 +38,17 @@ final class ConfigurationException extends OrmException
|
||||
$max,
|
||||
));
|
||||
}
|
||||
|
||||
/**
|
||||
* @param list<string> $unknown
|
||||
* @param list<string> $known
|
||||
*/
|
||||
public static function unknownSeeder(array $unknown, array $known): self
|
||||
{
|
||||
return new self(sprintf(
|
||||
'Unknown seeder(s): %s. Registered: %s.',
|
||||
implode(', ', $unknown),
|
||||
$known === [] ? '(none)' : implode(', ', $known),
|
||||
));
|
||||
}
|
||||
}
|
||||
@@ -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;
|
||||
}
|
||||
}
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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,
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user