From 6d0f0f27d4bc2b96bfbe0d5f91a06bb9d9347eed Mon Sep 17 00:00:00 2001 From: brendt Date: Fri, 4 Jul 2025 15:07:14 +0200 Subject: [PATCH] wip --- composer.json | 2 +- composer.lock | 27 ++++---- .../content/1.x/1-essentials/03-database.md | 67 ++++++++++++++++++- .../content/main/1-essentials/03-database.md | 67 ++++++++++++++++++- 4 files changed, 146 insertions(+), 17 deletions(-) diff --git a/composer.json b/composer.json index b3490b43..6952e0aa 100644 --- a/composer.json +++ b/composer.json @@ -3,7 +3,7 @@ "type": "project", "description": "Documentation website for the Tempest framework", "require": { - "tempest/framework": "dev-main", + "tempest/framework": "dev-database-seeders", "league/commonmark": "^2.7.0", "symfony/yaml": "^7.3.1", "spatie/yaml-front-matter": "^2.1", diff --git a/composer.lock b/composer.lock index d6c21fa0..961cab24 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "33dad01810c831513b75580eb187bd4e", + "content-hash": "0dd0873faa76b80066ee020913e129ec", "packages": [ { "name": "assertchris/ellison", @@ -3937,16 +3937,16 @@ }, { "name": "tempest/framework", - "version": "dev-main", + "version": "dev-database-seeders", "source": { "type": "git", "url": "https://github.com/tempestphp/tempest-framework.git", - "reference": "d28e89613d1a6c39f367b5d421a11d66ec2b9bc2" + "reference": "87214e0ef6c6882d139c757fdf0d22b995254118" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/tempestphp/tempest-framework/zipball/d28e89613d1a6c39f367b5d421a11d66ec2b9bc2", - "reference": "d28e89613d1a6c39f367b5d421a11d66ec2b9bc2", + "url": "https://api.github.com/repos/tempestphp/tempest-framework/zipball/87214e0ef6c6882d139c757fdf0d22b995254118", + "reference": "87214e0ef6c6882d139c757fdf0d22b995254118", "shasum": "" }, "require": { @@ -4046,7 +4046,6 @@ "ext-pcntl": "Required to use some interactive console components.", "ext-posix": "Required to use some interactive console components." }, - "default-branch": true, "bin": [ "packages/console/bin/tempest" ], @@ -4122,7 +4121,7 @@ "description": "The PHP framework that gets out of your way.", "support": { "issues": "https://github.com/tempestphp/tempest-framework/issues", - "source": "https://github.com/tempestphp/tempest-framework/tree/main" + "source": "https://github.com/tempestphp/tempest-framework/tree/database-seeders" }, "funding": [ { @@ -4130,7 +4129,7 @@ "type": "github" } ], - "time": "2025-07-02T10:00:35+00:00" + "time": "2025-07-04T12:38:06+00:00" }, { "name": "tempest/highlight", @@ -4923,16 +4922,16 @@ }, { "name": "phpunit/phpunit", - "version": "12.2.5", + "version": "12.2.6", "source": { "type": "git", "url": "https://github.com/sebastianbergmann/phpunit.git", - "reference": "b71849b29f7a8d7574e4401873cb8b539896613f" + "reference": "638644c62a58f04974da115f98981c9b48564021" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/sebastianbergmann/phpunit/zipball/b71849b29f7a8d7574e4401873cb8b539896613f", - "reference": "b71849b29f7a8d7574e4401873cb8b539896613f", + "url": "https://api.github.com/repos/sebastianbergmann/phpunit/zipball/638644c62a58f04974da115f98981c9b48564021", + "reference": "638644c62a58f04974da115f98981c9b48564021", "shasum": "" }, "require": { @@ -5000,7 +4999,7 @@ "support": { "issues": "https://github.com/sebastianbergmann/phpunit/issues", "security": "https://github.com/sebastianbergmann/phpunit/security/policy", - "source": "https://github.com/sebastianbergmann/phpunit/tree/12.2.5" + "source": "https://github.com/sebastianbergmann/phpunit/tree/12.2.6" }, "funding": [ { @@ -5024,7 +5023,7 @@ "type": "tidelift" } ], - "time": "2025-06-27T04:37:55+00:00" + "time": "2025-07-04T06:00:16+00:00" }, { "name": "sebastian/cli-parser", diff --git a/src/Web/Documentation/content/1.x/1-essentials/03-database.md b/src/Web/Documentation/content/1.x/1-essentials/03-database.md index f7b402c3..6e52935e 100644 --- a/src/Web/Documentation/content/1.x/1-essentials/03-database.md +++ b/src/Web/Documentation/content/1.x/1-essentials/03-database.md @@ -503,9 +503,74 @@ You may use the `migrate:rehash` command to bypass migration integrity checks an ``` :::warning -Note that deliberately bypassing migration integrity checks may result in a broken database state. Only use this command when absolutely necessary, if you are confident that your migration files are correct and consistent accross environments. +Note that deliberately bypassing migration integrity checks may result in a broken database state. Only use this command when necessary if you are confident that your migration files are correct and consistent across environments. ::: +## Database seeders + +Whenever you need to fill your database with dummy data, you can provide database seeders. These are classes that are used to fill your database with whatever data you want. To get started, you should implement the `\Tempest\Database\DatabaseSeeder` interface. + +```php +use Tempest\Database\DatabaseSeeder; +use UnitEnum; + +final class BookSeeder implements DatabaseSeeder +{ + public function run(null|string|UnitEnum $database): void + { + query(Book::class) + ->insert( + title: 'Timeline Taxi', + ) + ->onDatabase($database) + ->execute(); + } +} +``` + +Note how the `$database` property is passed into the `run()` method. In case a user has specified a database for this seeder to run on, this property will reflect that choice. + +Running database seeders can be done in two ways: either via the `database:seed` command, or via the `migrate:fresh` command. Not that `database:seed` will always append the seeded data on the existing database. + +```console +./tempest database:seed +./tempest migrate:fresh --seed +``` + +### Multiple seeders + +If you want to, you can create multiple seeder classes. Each seeder class could be used to bring the database into a specific state, or you could use multiple seeder classes to seed specific parts of your database. + +Whenever you have multiple seeder classes, Tempest will prompt you which ones to run: + +```console +./tempest database:seed + + │ Which seeders do you want to run? + │ / Filter... + │ → ⋅ Tests\Tempest\Fixtures\MailingSeeder + │ ⋅ Tests\Tempest\Fixtures\InvoiceSeeder +``` + +Both the `database:seed` and `migrate:fresh` commands also allow to pick one specific seeder or run all seeders automatically. + +```console +./tempest database:seed --all +./tempest database:seed --seeder="Tests\Tempest\Fixtures\MailingSeeder" + +./tempest migrate:fresh --seed --all +./tempest migrate:fresh --seeder="Tests\Tempest\Fixtures\MailingSeeder" +``` + +### Seeding on multiple databases + +Seeders have built-in support for multiple databases, which you can specify with the `--database` option. Continue reading to learn more about multiple databases. + +```console +./tempest database:seed --database="backup" +./tempest migrate:fresh --database="main" +``` + ## Multiple databases Tempest supports connecting to multiple databases at once. This can, for example, be useful to transfer data between databases or build multi-tenant systems. diff --git a/src/Web/Documentation/content/main/1-essentials/03-database.md b/src/Web/Documentation/content/main/1-essentials/03-database.md index 3cb3d9f1..e5c8f0a0 100644 --- a/src/Web/Documentation/content/main/1-essentials/03-database.md +++ b/src/Web/Documentation/content/main/1-essentials/03-database.md @@ -503,9 +503,74 @@ You may use the `migrate:rehash` command to bypass migration integrity checks an ``` :::warning -Note that deliberately bypassing migration integrity checks may result in a broken database state. Only use this command when absolutely necessary, if you are confident that your migration files are correct and consistent accross environments. +Note that deliberately bypassing migration integrity checks may result in a broken database state. Only use this command when necessary if you are confident that your migration files are correct and consistent across environments. ::: +## Database seeders + +Whenever you need to fill your database with dummy data, you can provide database seeders. These are classes that are used to fill your database with whatever data you want. To get started, you should implement the `\Tempest\Database\DatabaseSeeder` interface. + +```php +use Tempest\Database\DatabaseSeeder; +use UnitEnum; + +final class BookSeeder implements DatabaseSeeder +{ + public function run(null|string|UnitEnum $database): void + { + query(Book::class) + ->insert( + title: 'Timeline Taxi', + ) + ->onDatabase($database) + ->execute(); + } +} +``` + +Note how the `$database` property is passed into the `run()` method. In case a user has specified a database for this seeder to run on, this property will reflect that choice. + +Running database seeders can be done in two ways: either via the `database:seed` command, or via the `migrate:fresh` command. Not that `database:seed` will always append the seeded data on the existing database. + +```console +./tempest database:seed +./tempest migrate:fresh --seed +``` + +### Multiple seeders + +If you want to, you can create multiple seeder classes. Each seeder class could be used to bring the database into a specific state, or you could use multiple seeder classes to seed specific parts of your database. + +Whenever you have multiple seeder classes, Tempest will prompt you which ones to run: + +```console +./tempest database:seed + + │ Which seeders do you want to run? + │ / Filter... + │ → ⋅ Tests\Tempest\Fixtures\MailingSeeder + │ ⋅ Tests\Tempest\Fixtures\InvoiceSeeder +``` + +Both the `database:seed` and `migrate:fresh` commands also allow to pick one specific seeder or run all seeders automatically. + +```console +./tempest database:seed --all +./tempest database:seed --seeder="Tests\Tempest\Fixtures\MailingSeeder" + +./tempest migrate:fresh --seed --all +./tempest migrate:fresh --seeder="Tests\Tempest\Fixtures\MailingSeeder" +``` + +### Seeding on multiple databases + +Seeders have built-in support for multiple databases, which you can specify with the `--database` option. Continue reading to learn more about multiple databases. + +```console +./tempest database:seed --database="backup" +./tempest migrate:fresh --database="main" +``` + ## Multiple databases Tempest supports connecting to multiple databases at once. This can, for example, be useful to transfer data between databases or build multi-tenant systems.