feat: add seeders with CLI commands, path resolver, and tests

Author: KolesnikovKirill

CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All significant changes to this project will be documented in this file.
 
+## [1.5.0] - 2025-12-21
+
+### Added
+
+-   **Seeders:** New seeding system with `Seeder`, `SeederRunner`, and `SeedPathResolver`.
+-   **CLI seed commands:** `seed` and `make:seed` with configurable default path (`./database/seeds`).
+-   **Seeder tests:** Coverage for runner behavior, path resolver, and CLI commands.
+-   **Docs:** README updated with seeder usage and configuration examples.
+
+### Changed
+
+-   CLI seed command output now uses stdout consistently for testability.
+
 ## [1.4.3] - 2025-12-10
 
 ### Fixed

README.md

@@ -291,6 +291,8 @@ The package includes a migration system (designed to be used via the CLI).
 -   `migrate:rollback`
 -   `migrate:status`
 -   `make:migration`
+-   `seed`
+-   `make:seed`
 
 ### Example migration
 
@@ -314,6 +316,26 @@ return new class extends Migration {
 };
 ```
 
+## Seeders
+
+The package includes a lightweight seeding system (via the CLI).
+
+### Example seeder
+
+```php
+use Codemonster\Database\Seeders\Seeder;
+
+return new class extends Seeder {
+    public function run(): void
+    {
+        db()->table('users')->insert([
+            'name' => 'Admin',
+            'email' => 'admin@example.com',
+        ]);
+    }
+};
+```
+
 ## ORM (ActiveRecord / Eloquent‑style)
 
 **Since 1.3.0**, the package includes a complete ORM layer:
@@ -469,6 +491,33 @@ You can override paths via the migration kernel/path resolver:
 $kernel->getPathResolver()->addPath('/path/to/migrations');
 ```
 
+### Running seeders
+
+```bash
+vendor/bin/database seed
+```
+
+### Create a seeder
+
+```bash
+vendor/bin/database make:seed UsersSeeder
+```
+
+Seed names must be CamelCase using only Latin letters (e.g., `UsersSeeder`). Names that include other symbols or casing styles are rejected.
+
+Default seeds directory:
+
+```text
+./database/seeds
+```
+
+You can override paths via the seed kernel/path resolver:
+
+```php
+$kernel->getSeedPathResolver()->addPath('/path/to/seeds');
+```
+
+
 ## Tests
 
 ```bash

src/CLI/Commands/MakeSeedCommand.php

@@ -0,0 +1,122 @@
+<?php
+
+namespace Codemonster\Database\CLI\Commands;
+
+use Codemonster\Database\CLI\CommandInterface;
+use Codemonster\Database\Seeders\SeedPathResolver;
+
+class MakeSeedCommand implements CommandInterface
+{
+    protected SeedPathResolver $paths;
+
+    public function __construct(SeedPathResolver $paths)
+    {
+        $this->paths = $paths;
+    }
+
+    public function signature(): string
+    {
+        return 'make:seed';
+    }
+
+    public function description(): string
+    {
+        return 'Create a new seed file';
+    }
+
+    public function handle(array $arguments): int
+    {
+        $name = $arguments[0] ?? null;
+
+        if (!$name) {
+            echo "Seed name is required.\n";
+            echo "Usage: make:seed UsersSeeder\n";
+
+            return 1;
+        }
+
+        if (!$this->isValidName($name)) {
+            echo "Seed name must be CamelCase, Latin letters only. Example: UsersSeeder\n";
+
+            return 1;
+        }
+
+        $path = $this->detectPath();
+
+        if (!$path) {
+            echo "No seeds path configured.\n";
+
+            return 1;
+        }
+
+        if (!is_dir($path) && !mkdir($path, 0777, true) && !is_dir($path)) {
+            echo "Cannot create seeds directory: {$path}\n";
+
+            return 1;
+        }
+
+        $filename = $this->buildFileName($name);
+        $fullPath = $path . DIRECTORY_SEPARATOR . $filename;
+
+        if (file_exists($fullPath)) {
+            echo "Seed file already exists: {$fullPath}\n";
+
+            return 1;
+        }
+
+        file_put_contents($fullPath, $this->stub());
+
+        echo "Created seed: {$fullPath}\n";
+
+        return 0;
+    }
+
+    protected function detectPath(): ?string
+    {
+        $paths = $this->paths->getPaths();
+
+        if (!empty($paths)) {
+            return $paths[0];
+        }
+
+        return null;
+    }
+
+    protected function isValidName(string $name): bool
+    {
+        return (bool) preg_match('/^[A-Z][a-z]*(?:[A-Z][a-z]*)*$/', $name);
+    }
+
+    protected function buildFileName(string $name): string
+    {
+        $now = new \DateTimeImmutable('now');
+        $timestamp = $now->format('Y_m_d_His');
+        $slug = preg_replace('/(?<!^)([A-Z])/', '_$1', $name);
+        $slug = preg_replace('/[^A-Za-z0-9]+/', '_', $slug);
+        $slug = trim($slug, '_');
+        $slug = strtolower($slug);
+
+        return $timestamp . '_' . $slug . '.php';
+    }
+
+    protected function stub(): string
+    {
+        return <<<PHP
+        <?php
+
+        use Codemonster\\Database\\Seeders\\Seeder;
+
+        return new class extends Seeder {
+            public function run(): void
+            {
+                // Example:
+                // db()->table('users')->insert([
+                //     'name' => 'Admin',
+                //     'email' => 'admin@example.com',
+                // ]);
+            }
+        };
+
+        PHP;
+    }
+}

src/CLI/Commands/SeedCommand.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace Codemonster\Database\CLI\Commands;
+
+use Codemonster\Database\CLI\CommandInterface;
+use Codemonster\Database\Seeders\SeederRunner;
+
+class SeedCommand implements CommandInterface
+{
+    protected SeederRunner $seeder;
+
+    public function __construct(SeederRunner $seeder)
+    {
+        $this->seeder = $seeder;
+    }
+
+    public function signature(): string
+    {
+        return 'seed';
+    }
+
+    public function description(): string
+    {
+        return 'Run all seeders';
+    }
+
+    public function handle(array $arguments): int
+    {
+        $executed = $this->seeder->seed();
+
+        if (empty($executed)) {
+            echo "Nothing to seed.\n";
+
+            return 0;
+        }
+
+        foreach ($executed as $name) {
+            echo "Seeded: {$name}\n";
+        }
+
+        return 0;
+    }
+}

src/CLI/DatabaseCLIKernel.php

@@ -6,10 +6,14 @@
 use Codemonster\Database\Migrations\MigrationPathResolver;
 use Codemonster\Database\Migrations\MigrationRepository;
 use Codemonster\Database\Migrations\Migrator;
+use Codemonster\Database\Seeders\SeedPathResolver;
+use Codemonster\Database\Seeders\SeederRunner;
 use Codemonster\Database\CLI\Commands\MigrateCommand;
 use Codemonster\Database\CLI\Commands\RollbackCommand;
 use Codemonster\Database\CLI\Commands\StatusCommand;
 use Codemonster\Database\CLI\Commands\MakeMigrationCommand;
+use Codemonster\Database\CLI\Commands\SeedCommand;
+use Codemonster\Database\CLI\Commands\MakeSeedCommand;
 
 class DatabaseCLIKernel
 {
@@ -19,17 +23,31 @@ class DatabaseCLIKernel
 
     protected Migrator $migrator;
 
-    public function __construct(ConnectionInterface $connection, ?MigrationPathResolver $paths = null)
-    {
+    protected SeedPathResolver $seedPaths;
+
+    protected SeederRunner $seeder;
+
+    public function __construct(
+        ConnectionInterface $connection,
+        ?MigrationPathResolver $paths = null,
+        ?SeedPathResolver $seedPaths = null
+    ) {
         $this->paths = $paths ?? new MigrationPathResolver();
 
         if (empty($this->paths->getPaths())) {
             $this->paths->addPath(getcwd() . DIRECTORY_SEPARATOR . 'database' . DIRECTORY_SEPARATOR . 'migrations');
         }
 
+        $this->seedPaths = $seedPaths ?? new SeedPathResolver();
+
+        if (empty($this->seedPaths->getPaths())) {
+            $this->seedPaths->addPath(getcwd() . DIRECTORY_SEPARATOR . 'database' . DIRECTORY_SEPARATOR . 'seeds');
+        }
+
         $repository = new MigrationRepository($connection);
 
         $this->migrator = new Migrator($repository, $connection, $this->paths);
+        $this->seeder = new SeederRunner($connection, $this->seedPaths);
         $this->commands = new CommandRegistry();
 
         $this->registerDefaultCommands();
@@ -41,6 +59,8 @@ protected function registerDefaultCommands(): void
         $this->commands->register(new RollbackCommand($this->migrator));
         $this->commands->register(new StatusCommand($this->migrator));
         $this->commands->register(new MakeMigrationCommand($this->paths));
+        $this->commands->register(new SeedCommand($this->seeder));
+        $this->commands->register(new MakeSeedCommand($this->seedPaths));
     }
 
     public function handle(array $argv): int
@@ -58,8 +78,18 @@ public function getPathResolver(): MigrationPathResolver
         return $this->paths;
     }
 
+    public function getSeedPathResolver(): SeedPathResolver
+    {
+        return $this->seedPaths;
+    }
+
     public function getMigrator(): Migrator
     {
         return $this->migrator;
     }
+
+    public function getSeeder(): SeederRunner
+    {
+        return $this->seeder;
+    }
 }

src/Seeders/SeedPathResolver.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace Codemonster\Database\Seeders;
+
+class SeedPathResolver
+{
+    /**
+     * @var string[]
+     */
+    protected array $paths = [];
+
+    /**
+     * Add seeders path (only if directory exists).
+     */
+    public function addPath(string $path): void
+    {
+        // Allow registering paths even before the directory exists; it can be created later by CLI
+        $this->paths[] = rtrim($path, DIRECTORY_SEPARATOR);
+
+        // Keep list unique to avoid duplicate lookups
+        $this->paths = array_values(array_unique($this->paths));
+    }
+
+    /**
+     * @return string[]
+     */
+    public function getPaths(): array
+    {
+        return $this->paths;
+    }
+}

src/Seeders/Seeder.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Codemonster\Database\Seeders;
+
+abstract class Seeder
+{
+    /**
+     * Run the seeder.
+     */
+    abstract public function run(): void;
+}