feat(console): add bin/camelia-orm with seed and make commands
Tests / PHP 8.4 (push) Failing after 3m23s

A command line for the library, kept deliberately small: no console
component, no dependency added to the consumer's tree.

- Application/Command/Input/Output: parsing, dispatch, exit codes and
  capturable output. Commands return an exit code instead of calling exit(),
  so every one is testable.
- seed: runs the registered SeederRunner inside one transaction, with
  --list and --only=name[,name].
- doctor: one round-trip that fails loudly when the DSN is wrong.
- make:model and make:seeder: live scaffolding into the consumer's code,
  sharing name validation, the overwrite guard and directory creation
  through MakeCommand.

The binary ships an empty runner; an application composes SeedCommand into
its own Application to register its seeders.
This commit is contained in:
dgarcia committed 2026-11-15 13:31:14 -03:00
1 parent 2acf2cc099
commit a655a6f3ae
16 files changed
+1576

No files matched your search

+171
View File
@@ -0,0 +1,171 @@
<?php
declare(strict_types=1);
namespace Camelia\Orm\Tests\Unit\Console;
use Camelia\Orm\Console\Application;
use Camelia\Orm\Console\Command;
use Camelia\Orm\Console\Input;
use Camelia\Orm\Console\Output;
use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\TestCase;
final class ApplicationTest extends TestCase
{
private string $printed = '';
private function console(): Output
{
return new Output(function (string $text): void {
$this->printed .= $text;
});
}
#[Test]
public function it_lists_registered_commands_with_their_description(): void
{
$application = new Application()->add($this->command('seed', 'Runs the seeders.'));
$exit = $application->run([], $this->console());
self::assertSame(Application::SUCCESS, $exit);
self::assertStringContainsString('seed', $this->printed);
self::assertStringContainsString('Runs the seeders.', $this->printed);
}
#[Test]
public function it_dispatches_to_the_named_command(): void
{
$application = new Application()->add($this->command('seed', 'desc'));
$exit = $application->run(['bin', 'seed'], $this->console());
self::assertSame(Application::SUCCESS, $exit);
self::assertStringContainsString('executed:seed', $this->printed);
}
#[Test]
public function it_passes_positional_arguments(): void
{
$application = new Application()->add($this->command('make:model', 'desc'));
$application->run(['bin', 'make:model', 'Invoice'], $this->console());
self::assertStringContainsString('args:Invoice', $this->printed);
}
#[Test]
public function it_passes_long_options_with_and_without_values(): void
{
$application = new Application()->add($this->command('seed', 'desc'));
$application->run(['bin', 'seed', '--only=roles', '--list'], $this->console());
self::assertStringContainsString('only=roles', $this->printed);
self::assertStringContainsString('list=1', $this->printed);
}
#[Test]
public function an_unknown_command_fails_with_a_non_zero_code(): void
{
$application = new Application()->add($this->command('seed', 'desc'));
$exit = $application->run(['bin', 'nope'], $this->console());
self::assertSame(Application::INVALID_USAGE, $exit);
self::assertStringContainsString('Unknown command "nope".', $this->printed);
}
#[Test]
public function help_prints_the_usage_of_one_command(): void
{
$application = new Application()->add($this->command('seed', 'desc'));
$application->run(['bin', 'help', 'seed'], $this->console());
self::assertStringContainsString('Usage: seed [--x]', $this->printed);
}
#[Test]
public function dash_dash_help_prints_the_usage_instead_of_running(): void
{
$application = new Application()->add($this->command('seed', 'desc'));
$application->run(['bin', 'seed', '--help'], $this->console());
self::assertStringContainsString('Usage: seed [--x]', $this->printed);
self::assertStringNotContainsString('executed:seed', $this->printed);
}
#[Test]
public function dash_dash_version_prints_the_version(): void
{
$application = new Application('camelia-orm', '9.9.9');
$application->run(['bin', '--version'], $this->console());
self::assertStringContainsString('camelia-orm 9.9.9', $this->printed);
}
#[Test]
public function input_splits_options_from_arguments(): void
{
$input = Input::fromArgv(['bin', 'seed', 'extra', '--only=a,b', '--list']);
self::assertSame('seed', $input->command);
self::assertSame(['extra'], $input->arguments);
self::assertSame('a,b', $input->option('only'));
self::assertTrue($input->hasOption('list'));
self::assertSame('', $input->option('list'));
}
#[Test]
public function input_splits_a_comma_separated_list_option(): void
{
$input = Input::fromArgv(['bin', 'seed', '--only=roles, admin-user ,']);
self::assertSame(['roles', 'admin-user'], $input->listOption('only'));
self::assertSame([], $input->listOption('missing'));
}
private function command(string $name, string $description): Command
{
return new class($name, $description) implements Command {
public function __construct(
private readonly string $label,
private readonly string $text,
) {}
public function name(): string
{
return $this->label;
}
public function description(): string
{
return $this->text;
}
public function usage(): string
{
return 'Usage: ' . $this->label . ' [--x]';
}
public function execute(array $arguments, array $options, Output $output): int
{
$output->writeln('executed:' . $this->label);
if ($arguments !== []) {
$output->writeln('args:' . implode(',', $arguments));
}
foreach ($options as $key => $value) {
$output->writeln($key . '=' . ($value === true ? '1' : $value));
}
return Application::SUCCESS;
}
};
}
}
+218
View File
@@ -0,0 +1,218 @@
<?php
declare(strict_types=1);
namespace Camelia\Orm\Tests\Unit\Console;
use Camelia\Orm\Console\Application;
use Camelia\Orm\Console\Command\MakeModelCommand;
use Camelia\Orm\Console\Command\MakeSeederCommand;
use Camelia\Orm\Console\Output;
use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\TestCase;
final class MakeCommandsTest extends TestCase
{
private string $directory = '';
private string $printed = '';
protected function setUp(): void
{
$this->directory =
sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'camelia_' . bin2hex(random_bytes(6));
}
protected function tearDown(): void
{
if ($this->directory === '' || !is_dir($this->directory)) {
return;
}
$files = glob($this->directory . DIRECTORY_SEPARATOR . '*');
foreach ($files === false ? [] : $files as $file) {
if (is_file($file)) {
unlink($file);
}
}
rmdir($this->directory);
}
private function console(): Output
{
return new Output(function (string $text): void {
$this->printed .= $text;
});
}
#[Test]
public function make_model_writes_a_model_with_the_orm_attributes(): void
{
$exit = new MakeModelCommand()->execute(
['Invoice'],
['table' => 'invoices', 'dir' => $this->directory, 'namespace' => 'App\\Models'],
$this->console(),
);
self::assertSame(Application::SUCCESS, $exit);
$contents = (string) file_get_contents(
$this->directory . DIRECTORY_SEPARATOR . 'Invoice.php',
);
self::assertStringContainsString('namespace App\\Models;', $contents);
self::assertStringContainsString("#[TableName('invoices')]", $contents);
self::assertStringContainsString('final class Invoice extends Model', $contents);
self::assertStringContainsString('#[PrimaryKey, AutoIncrement]', $contents);
}
#[Test]
public function make_model_generates_valid_php(): void
{
new MakeModelCommand()->execute(
['Invoice'],
['table' => 'invoices', 'dir' => $this->directory],
$this->console(),
);
self::assertSame(
'No syntax errors detected in '
. str_replace(
['\\', '/'],
'/',
$this->directory . DIRECTORY_SEPARATOR . 'Invoice.php',
),
$this->lint('Invoice.php'),
);
}
#[Test]
public function make_model_requires_a_table(): void
{
$exit = new MakeModelCommand()->execute(['Invoice'], [], $this->console());
self::assertSame(Application::INVALID_USAGE, $exit);
self::assertStringContainsString('--table=<table>', $this->printed);
}
#[Test]
public function make_model_requires_a_pascal_case_name(): void
{
$exit = new MakeModelCommand()->execute(
['invoice'],
['table' => 'invoices', 'dir' => $this->directory],
$this->console(),
);
self::assertSame(Application::INVALID_USAGE, $exit);
self::assertStringContainsString('PascalCase', $this->printed);
}
#[Test]
public function make_model_refuses_to_overwrite_without_force(): void
{
new MakeModelCommand()->execute(
['Invoice'],
['table' => 'invoices', 'dir' => $this->directory],
$this->console(),
);
$exit = new MakeModelCommand()->execute(
['Invoice'],
['table' => 'other', 'dir' => $this->directory],
$this->console(),
);
self::assertSame(Application::FAILURE, $exit);
self::assertStringContainsString(
"#[TableName('invoices')]",
(string) file_get_contents($this->directory . DIRECTORY_SEPARATOR . 'Invoice.php'),
);
}
#[Test]
public function make_model_overwrites_when_forced(): void
{
new MakeModelCommand()->execute(
['Invoice'],
['table' => 'invoices', 'dir' => $this->directory],
$this->console(),
);
new MakeModelCommand()->execute(
['Invoice'],
['table' => 'other', 'dir' => $this->directory, 'force' => true],
$this->console(),
);
self::assertStringContainsString(
"#[TableName('other')]",
(string) file_get_contents($this->directory . DIRECTORY_SEPARATOR . 'Invoice.php'),
);
}
#[Test]
public function make_seeder_writes_a_seeder_extending_abstract_seeder(): void
{
$exit = new MakeSeederCommand()->execute(
['RolesSeeder'],
['dir' => $this->directory, 'namespace' => 'App\\Seeders'],
$this->console(),
);
self::assertSame(Application::SUCCESS, $exit);
$contents = (string) file_get_contents(
$this->directory . DIRECTORY_SEPARATOR . 'RolesSeeder.php',
);
self::assertStringContainsString('namespace App\\Seeders;', $contents);
self::assertStringContainsString(
'final class RolesSeeder extends AbstractSeeder',
$contents,
);
self::assertStringContainsString("return 'roles';", $contents);
self::assertStringContainsString('public function run(Orm $orm): void', $contents);
}
#[Test]
public function make_seeder_generates_valid_php(): void
{
new MakeSeederCommand()->execute(
['RolesSeeder'],
['dir' => $this->directory],
$this->console(),
);
self::assertSame(
'No syntax errors detected in '
. str_replace(
['\\', '/'],
'/',
$this->directory . DIRECTORY_SEPARATOR . 'RolesSeeder.php',
),
$this->lint('RolesSeeder.php'),
);
}
/**
* `php -l` prints its verdict on the first line; the path separator differs per platform.
*/
private function lint(string $file): string
{
$output = [];
exec(
escapeshellarg(PHP_BINARY)
. ' -l '
. escapeshellarg($this->directory . DIRECTORY_SEPARATOR . $file)
. ' 2>&1',
$output,
);
$first = $output[0] ?? '';
return trim(str_replace(['\\', '/'], '/', $first));
}
}
+159
View File
@@ -0,0 +1,159 @@
<?php
declare(strict_types=1);
namespace Camelia\Orm\Tests\Unit\Console;
use Camelia\Orm\Console\Application;
use Camelia\Orm\Console\Command\SeedCommand;
use Camelia\Orm\Console\Output;
use Camelia\Orm\Orm;
use Camelia\Orm\Seeding\AbstractSeeder;
use Camelia\Orm\Seeding\SeederRunner;
use Camelia\Orm\Tests\Support\FakeConnection;
use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\TestCase;
final class SeedCommandTest extends TestCase
{
private string $printed = '';
private function console(): Output
{
return new Output(function (string $text): void {
$this->printed .= $text;
});
}
private function orm(): Orm
{
return Orm::fromConnection(new FakeConnection());
}
private function command(): SeedCommand
{
return new SeedCommand(
$this->orm(...),
static fn(Orm $orm): SeederRunner => new SeederRunner($orm),
);
}
#[Test]
public function list_prints_registered_seeder_names(): void
{
$command = new SeedCommand(
$this->orm(...),
static fn(Orm $orm): SeederRunner => new SeederRunner($orm)->addMany([
new class extends AbstractSeeder {
public function name(): string
{
return 'permissions';
}
public function run(Orm $orm): void {}
},
new class extends AbstractSeeder {
public function name(): string
{
return 'roles';
}
public function run(Orm $orm): void {}
},
]),
);
$exit = $command->execute([], ['list' => true], $this->console());
self::assertSame(Application::SUCCESS, $exit);
self::assertStringContainsString('permissions', $this->printed);
self::assertStringContainsString('roles', $this->printed);
}
#[Test]
public function it_reports_no_seeders_registered(): void
{
$exit = $this->command()->execute([], [], $this->console());
self::assertSame(Application::SUCCESS, $exit);
self::assertStringContainsString('No seeders registered.', $this->printed);
}
#[Test]
public function it_runs_only_the_seeders_named_in_only(): void
{
$ran = new \ArrayObject();
$command = new SeedCommand($this->orm(...), static function (Orm $orm) use (
$ran,
): SeederRunner {
$a = new class($ran) extends AbstractSeeder {
/** @param \ArrayObject<int, string> $ran */
public function __construct(
private readonly \ArrayObject $ran,
) {}
public function name(): string
{
return 'permissions';
}
public function run(Orm $orm): void
{
$this->ran->append('permissions');
}
};
$b = new class($ran) extends AbstractSeeder {
/** @param \ArrayObject<int, string> $ran */
public function __construct(
private readonly \ArrayObject $ran,
) {}
public function name(): string
{
return 'roles';
}
public function run(Orm $orm): void
{
$this->ran->append('roles');
}
};
return new SeederRunner($orm)->addMany([$a, $b]);
});
$exit = $command->execute([], ['only' => 'roles'], $this->console());
self::assertSame(Application::SUCCESS, $exit);
self::assertSame(['roles'], $ran->getArrayCopy());
self::assertStringContainsString('roles: 0 inserted, 0 skipped', $this->printed);
}
#[Test]
public function it_reports_a_seeder_failure_without_a_stack_trace(): void
{
$command = new SeedCommand(
$this->orm(...),
static fn(Orm $orm): SeederRunner => new SeederRunner($orm)->add(new class extends
AbstractSeeder {
public function name(): string
{
return 'boom';
}
public function run(Orm $orm): void
{
throw new \RuntimeException('table missing');
}
}),
);
$exit = $command->execute([], [], $this->console());
self::assertSame(Application::FAILURE, $exit);
self::assertStringContainsString('Seeding failed, nothing was written', $this->printed);
self::assertStringContainsString('table missing', $this->printed);
}
}