fa/breadcrumb-the-shire
1
0
Fork 1
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat(console): add db:migrate CLI for idempotent core schema updates

Browse Source 
Existing systems used to have no automatic mechanism for the
db/updates/*.sql idempotent updates after `git pull` — devs had to
remember which files were already applied and run new ones manually
with `mariadb < ...`. Mirror module:migrate to fix this:

- New `bin/console db:migrate` walks db/updates/*.sql in alphabetical
  order, skipping anything already recorded in the new core_migrations
  tracking table. Each file runs in its own transaction; failure
  rolls back so the file is retried on the next run.
- New `db:migrate --status` lists applied vs. pending files without
  running anything. Useful for ops debugging "schema seems stale"
  symptoms.
- module:sync now runs db:migrate as its first step, so the standard
  post-pull command stays a single invocation. README's 3-step setup
  is unchanged — module:sync now also covers core schema updates.

CoreMigrationRepository owns its own mysqli connection (using the
same DB credentials as MintyPHP\DB) and runs raw `$mysqli->query()`
instead of going through DB::query's prepared statement path —
MariaDB rejects some DDL (e.g. ALTER TABLE … ADD CONSTRAINT CHECK)
in the prepared protocol, which the existing 18 db/updates files
trip on. ModuleMigrationRepository is left untouched (no module
migration uses such DDL today and changing the vendor pattern is
out of scope).

End-to-end verified: against an existing DB the first run applies
all 19 idempotent files as no-ops and records them, second run
reports "all updates already applied". Against a freshly init'd
DB the same thing happens — no double work, no surprises. All
encrypted seed secrets keep decrypting because APP_CRYPTO_KEY
is unchanged.

Tests: tests/Console/CoreCommandsTest covers success/failure/status
output shapes against a FakeModuleRunner (mirror of the existing
ModuleCommandsTest pattern). 5 stale baseline entries in
phpstan-baseline removed (covered by the new @api annotation on
the test fixture class).

Docs: CLAUDE.md and docs/reference-cli-commands.md document the
new command + --status flag; docs/howto-fehlerbehebung.md gains
a "schema seems stale after git pull" section pointing at
db:migrate --status.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Felix Schneider
2026-04-29 08:59:57 +02:00
parent 0c78dc4355
commit 2e73cb98b4
17 changed files with 651 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
CLAUDE.md
View File

@@ -37,7 +37,9 @@ docker compose exec php vendor/bin/phpstan analyse -c phpstan.neon --no-progress
# CLI commands (single entry point)
docker compose exec php php bin/console list
docker compose exec php php bin/console module:sync # full module runtime sync
docker compose exec php php bin/console module:sync # full sync: db:migrate → module:migrate → permissions → build → assets
docker compose exec php php bin/console db:migrate # apply core db/updates/*.sql idempotently
docker compose exec php php bin/console db:migrate --status # list applied vs. pending core migrations
docker compose exec php php bin/console module:migrate # apply module SQL migrations
docker compose exec php php bin/console module:permissions-sync # sync + deactivate orphaned
docker compose exec php php bin/console module:build # build runtime page root

2
config/config.php
View File

@@ -1,7 +1,7 @@
<?php
use MintyPHP\Auth;
use MintyPHP\App\Bootstrap\EnvValidator;
use MintyPHP\Auth;
use MintyPHP\Cache;
use MintyPHP\DB;
use MintyPHP\Debugger;

9
core/App/Container/Registrars/AppServicesRegistrar.php
View File

@@ -17,6 +17,8 @@ use MintyPHP\Http\RequestRuntimeInterface;
use MintyPHP\Http\SessionStore;
use MintyPHP\Http\SessionStoreInterface;
use MintyPHP\Repository\Access\PermissionRepository;
use MintyPHP\Repository\Database\CoreMigrationRepository;
use MintyPHP\Repository\Database\CoreMigrationRepositoryInterface;
use MintyPHP\Repository\Module\ModuleMigrationRepository;
use MintyPHP\Repository\Search\SearchQueryRepository;
use MintyPHP\Repository\Stats\AdminStatsRepository;
@@ -27,6 +29,7 @@ use MintyPHP\Service\CustomField\CustomFieldServicesFactory;
use MintyPHP\Service\CustomField\TenantCustomFieldService;
use MintyPHP\Service\CustomField\UserCustomFieldValueService;
use MintyPHP\Service\Data\GridUserCountEnricher;
use MintyPHP\Service\Database\CoreMigrationService;
use MintyPHP\Service\Import\ImportService;
use MintyPHP\Service\Import\ImportServicesFactory;
use MintyPHP\Service\Mail\MailLogService;
@@ -84,6 +87,12 @@ final class AppServicesRegistrar implements ContainerRegistrar
$c->get(ModuleRegistry::class),
$c->get(ModuleMigrationRepository::class)
));
$container->set(CoreMigrationRepository::class, static fn (): CoreMigrationRepository => new CoreMigrationRepository());
$container->set(CoreMigrationRepositoryInterface::class, static fn (AppContainer $c): CoreMigrationRepositoryInterface => $c->get(CoreMigrationRepository::class));
$container->set(CoreMigrationService::class, fn (AppContainer $c): CoreMigrationService => new CoreMigrationService(
$c->get(CoreMigrationRepositoryInterface::class),
$projectRoot . '/db/updates'
));
$container->set(ModulePermissionSynchronizer::class, fn (AppContainer $c): ModulePermissionSynchronizer => new ModulePermissionSynchronizer(
$c->get(ModuleRegistry::class),
$c->get(PermissionRepository::class),

90
core/Console/Commands/Database/MigrateCommand.php Normal file
View File

@@ -0,0 +1,90 @@
<?php
namespace MintyPHP\Console\Commands\Database;
use MintyPHP\Console\Commands\Module\AbstractModuleCommand;
use MintyPHP\Console\Runner\Module\ModuleRunnerInterface;
/**
* Apply pending core SQL migrations from db/updates/.
*
* Mirror of `module:migrate` for core schema changes. Each `db/updates/*.sql`
* file MUST be idempotent; applied filenames are tracked in `core_migrations`.
*
* `--status` prints applied/pending lists without running anything.
*/
final class MigrateCommand extends AbstractModuleCommand
{
public function __construct(?ModuleRunnerInterface $moduleRunner = null)
{
parent::__construct($moduleRunner);
}
public function name(): string
{
return 'db:migrate';
}
public function description(): string
{
return 'Apply pending core SQL migrations from db/updates/';
}
public function usage(): string
{
return <<<'USAGE'
Usage: php bin/console db:migrate [--status]
Options:
--status Print applied / pending migration filenames without running anything
Each file under db/updates/*.sql is applied at most once and tracked in
the core_migrations table. Files MUST be idempotent (e.g. CREATE TABLE
IF NOT EXISTS, INSERT … ON DUPLICATE KEY UPDATE) so first-run on an
existing schema is a no-op.
`bin/console module:sync` runs db:migrate as its first step.
USAGE;
}
public function execute(array $args, array $options): int
{
if (!empty($options['status'])) {
$status = $this->moduleRunner()->dbMigrateStatus();
$appliedCount = count($status['applied']);
$pendingCount = count($status['pending']);
echo sprintf("db-migrate-status: %d applied, %d pending\n\n", $appliedCount, $pendingCount);
echo "applied:\n";
if ($appliedCount === 0) {
echo " (none)\n";
} else {
foreach ($status['applied'] as $filename) {
echo ' ' . $filename . PHP_EOL;
}
}
echo "\npending:\n";
if ($pendingCount === 0) {
echo " (none)\n";
} else {
foreach ($status['pending'] as $filename) {
echo ' ' . $filename . PHP_EOL;
}
}
return 0;
}
$result = $this->moduleRunner()->dbMigrate();
if ($result['exit_code'] === 0) {
echo $result['message'] . PHP_EOL;
} else {
fwrite(STDERR, $result['message'] . PHP_EOL);
}
return (int) $result['exit_code'];
}
}

67
core/Console/Runner/Module/ModuleRunner.php
View File

@@ -11,11 +11,73 @@ use MintyPHP\App\Module\ModulePermissionSynchronizer;
use MintyPHP\App\Module\ModuleRegistry;
use MintyPHP\App\Module\ModuleRuntimeAssetPublisher;
use MintyPHP\App\Module\ModuleRuntimePageBuilder;
use MintyPHP\Console\Support\CliAppBootstrap;
use MintyPHP\Console\Support\ModuleCliRuntime;
use MintyPHP\Service\Database\CoreMigrationService;
use MintyPHP\Service\Module\ModuleMigrationService;
final class ModuleRunner implements ModuleRunnerInterface
{
public function dbMigrate(): array
{
$summary = ['applied' => 0, 'skipped_empty' => 0, 'total_files' => 0, 'applied_filenames' => []];
$message = 'db-migrate: all updates already applied.';
$step = ModuleCliRuntime::runStep('db-migrate', function () use (&$summary, &$message): int {
$lockResult = ModuleCliRuntime::withFileLock(
ModuleCliRuntime::projectRoot() . '/storage/runtime/.db-migrate.lock',
'db-migrate: another migration run is in progress, skipping.',
function () use (&$summary, &$message): int {
/** @var CoreMigrationService $service */
$service = app(CoreMigrationService::class);
$result = $service->applyPendingMigrations();
$summary = $result;
if ($result['total_files'] === 0) {
$message = 'db-migrate: no update files in db/updates/, nothing to do.';
} elseif ($result['applied'] === 0) {
$message = 'db-migrate: all updates already applied.';
} else {
$message = sprintf('db-migrate: applied %d migration(s).', $result['applied']);
}
if ($result['skipped_empty'] > 0) {
$message .= sprintf(' (%d empty file(s) skipped)', $result['skipped_empty']);
}
return $result['ok'] ? 0 : 1;
}
);
if ($lockResult['busy']) {
$message = (string) $lockResult['message'];
}
return $lockResult['exit_code'];
});
return [
'command' => 'db:migrate',
'status' => $step['status'],
'exit_code' => $step['exit_code'],
'vendor_warnings_ignored' => $step['vendor_warnings_ignored'],
'message' => $step['error'] ?? $message,
];
}
public function dbMigrateStatus(): array
{
CliAppBootstrap::bootstrap('cli', 'bin/console db:migrate --status');
/** @var CoreMigrationService $service */
$service = app(CoreMigrationService::class);
$status = $service->status();
return [
'command' => 'db:migrate --status',
'applied' => $status['applied'],
'pending' => $status['pending'],
];
}
public function migrate(): array
{
$summary = ['applied' => 0, 'modules_enabled' => 0, 'skipped_empty' => 0];
@@ -287,6 +349,7 @@ final class ModuleRunner implements ModuleRunnerInterface
{
$startedAt = microtime(true);
$steps = [
'db-migrate' => ['status' => 'pending', 'exit_code' => 0, 'vendor_warnings_ignored' => 0],
'migrate' => ['status' => 'pending', 'exit_code' => 0, 'vendor_warnings_ignored' => 0],
'permissions-sync' => ['status' => 'pending', 'exit_code' => 0, 'vendor_warnings_ignored' => 0],
'build' => ['status' => 'pending', 'exit_code' => 0, 'vendor_warnings_ignored' => 0],
@@ -300,6 +363,7 @@ final class ModuleRunner implements ModuleRunnerInterface
'module-runtime-sync: another runtime sync is in progress, skipping.',
function () use (&$steps): int {
$orderedSteps = [
'db-migrate' => fn (): array => $this->dbMigrate(),
'migrate' => fn (): array => $this->migrate(),
'permissions-sync' => fn (): array => $this->permissionsSync(),
'build' => fn (): array => $this->build(),
@@ -332,7 +396,8 @@ final class ModuleRunner implements ModuleRunnerInterface
if ($message === '') {
$message = sprintf(
'module-runtime-sync: summary migrate=%s permissions-sync=%s build=%s assets-sync=%s vendor_warnings_ignored=%d',
'module-runtime-sync: summary db-migrate=%s migrate=%s permissions-sync=%s build=%s assets-sync=%s vendor_warnings_ignored=%d',
$steps['db-migrate']['status'],
$steps['migrate']['status'],
$steps['permissions-sync']['status'],
$steps['build']['status'],

13
core/Console/Runner/Module/ModuleRunnerInterface.php
View File

@@ -6,6 +6,16 @@ namespace MintyPHP\Console\Runner\Module;
interface ModuleRunnerInterface
{
/**
* @return array{command: string, status: string, exit_code: int, vendor_warnings_ignored: int, message: string}
*/
public function dbMigrate(): array;
/**
* @return array{command: string, applied: list<string>, pending: list<string>}
*/
public function dbMigrateStatus(): array;
/**
* @return array{command: string, status: string, exit_code: int, vendor_warnings_ignored: int, message: string}
*/
@@ -77,6 +87,9 @@ interface ModuleRunnerInterface
* steps: array<string, array{status: string, exit_code: int, vendor_warnings_ignored: int}>,
* message: string
* }
*
* The `steps` map is keyed in execution order:
* `db-migrate`, `migrate`, `permissions-sync`, `build`, `assets-sync`.
*/
public function runtimeSync(): array;
}

127
core/Repository/Database/CoreMigrationRepository.php Normal file
View File

@@ -0,0 +1,127 @@
<?php
namespace MintyPHP\Repository\Database;
use MintyPHP\DB;
use MintyPHP\DBError;
use mysqli;
/**
* Manages the core_migrations tracking table and applies raw SQL statements.
*
* Owns its own mysqli connection (using the same credentials as MintyPHP\DB)
* so we can run statements via mysqli->query() — bypassing prepared statements,
* which MariaDB rejects for some DDL (e.g. ALTER TABLE … ADD CONSTRAINT CHECK).
*
* All SQL for core migration tracking lives here (strict layering).
*/
final class CoreMigrationRepository implements CoreMigrationRepositoryInterface
{
private ?mysqli $mysqli = null;
public function ensureTrackingTable(): void
{
$this->executeStatement(
'CREATE TABLE IF NOT EXISTS `core_migrations` (
`id` INT UNSIGNED NOT NULL AUTO_INCREMENT,
`filename` VARCHAR(255) NOT NULL,
`applied_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (`id`),
UNIQUE KEY `uq_core_migration` (`filename`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci'
);
}
/**
* @return array<string, true> Filenames already applied, keyed by filename
*/
public function getAppliedFilenames(): array
{
$applied = [];
$result = $this->connection()->query('SELECT filename FROM core_migrations');
if ($result === false) {
throw new DBError('Failed to query core_migrations: ' . $this->connection()->error);
}
while (($row = $result->fetch_assoc()) !== null) {
$filename = trim((string) ($row['filename'] ?? ''));
if ($filename !== '') {
$applied[$filename] = true;
}
}
$result->free();
return $applied;
}
public function recordApplied(string $filename): void
{
$stmt = $this->connection()->prepare('INSERT INTO core_migrations (filename) VALUES (?)');
if ($stmt === false) {
throw new DBError('Failed to prepare INSERT into core_migrations: ' . $this->connection()->error);
}
$stmt->bind_param('s', $filename);
$stmt->execute();
if ($stmt->errno !== 0) {
$error = $stmt->error;
$stmt->close();
throw new DBError('Failed to insert into core_migrations: ' . $error);
}
$stmt->close();
}
public function beginTransaction(): void
{
$this->executeStatement('START TRANSACTION');
}
public function commit(): void
{
$this->executeStatement('COMMIT');
}
public function rollback(): void
{
$this->executeStatement('ROLLBACK');
}
public function executeStatement(string $sql): void
{
$mysqli = $this->connection();
$result = $mysqli->query($sql);
if ($result === false) {
throw new DBError($mysqli->error);
}
// For SELECT-style results, free the result set so the connection
// doesn't get stuck in "commands out of sync" state.
if ($result instanceof \mysqli_result) {
$result->free();
}
}
private function connection(): mysqli
{
if ($this->mysqli instanceof mysqli) {
return $this->mysqli;
}
// Reuse the MintyPHP\DB connection settings (public statics) so we
// hit the same database the rest of the app uses, but with our own
// socket — the vendor DB class always uses prepared statements,
// which MariaDB rejects for some DDL.
$args = array_filter(
[DB::$host, DB::$username, DB::$password, DB::$database, DB::$port, DB::$socket],
static fn ($v): bool => $v !== null
);
$reflect = new \ReflectionClass(mysqli::class);
$mysqli = $reflect->newInstanceArgs($args);
if ($mysqli->connect_errno !== 0) {
throw new DBError('Failed to connect to database for core migrations: ' . $mysqli->connect_error);
}
if (!$mysqli->set_charset('utf8mb4')) {
throw new DBError('Failed to set charset for core migrations connection: ' . $mysqli->error);
}
$this->mysqli = $mysqli;
return $mysqli;
}
}

24
core/Repository/Database/CoreMigrationRepositoryInterface.php Normal file
View File

@@ -0,0 +1,24 @@
<?php
namespace MintyPHP\Repository\Database;
/** Contract for core migration tracking: table creation, applied-file queries, and statement execution. */
interface CoreMigrationRepositoryInterface
{
public function ensureTrackingTable(): void;
/**
* @return array<string, true>
*/
public function getAppliedFilenames(): array;
public function recordApplied(string $filename): void;
public function beginTransaction(): void;
public function commit(): void;
public function rollback(): void;
public function executeStatement(string $sql): void;
}

130
core/Service/Database/CoreMigrationService.php Normal file
View File

@@ -0,0 +1,130 @@
<?php
namespace MintyPHP\Service\Database;
use MintyPHP\Repository\Database\CoreMigrationRepositoryInterface;
use MintyPHP\Support\SqlStatementParser;
use RuntimeException;
/**
* Discovers and applies pending SQL migrations from db/updates/*.sql.
*
* Mirror of ModuleMigrationService for core schema changes. Each file MUST be
* idempotent (CLAUDE.md / GR-CORE-010); applied filenames are tracked in
* core_migrations so subsequent runs only apply genuinely new files.
*
* Orchestration only — SQL lives in CoreMigrationRepository,
* statement parsing in SqlStatementParser.
*/
final class CoreMigrationService
{
public function __construct(
private readonly CoreMigrationRepositoryInterface $repository,
private readonly string $updatesPath,
) {
}
/**
* Apply all pending core migrations.
*
* @return array{ok: bool, applied: int, skipped_empty: int, total_files: int, applied_filenames: list<string>}
*/
public function applyPendingMigrations(): array
{
$this->repository->ensureTrackingTable();
$files = $this->discoverFiles();
$applied = $this->repository->getAppliedFilenames();
$totalApplied = 0;
$skippedEmpty = 0;
$appliedFilenames = [];
foreach ($files as $file) {
$filename = basename($file);
if (isset($applied[$filename])) {
continue;
}
$sql = file_get_contents($file);
if ($sql === false || trim($sql) === '') {
$skippedEmpty++;
continue;
}
$this->repository->beginTransaction();
try {
$statements = SqlStatementParser::splitStatements($sql);
foreach ($statements as $statement) {
$this->repository->executeStatement($statement);
}
$this->repository->recordApplied($filename);
$this->repository->commit();
} catch (\Throwable $migrationError) {
$this->repository->rollback();
throw new RuntimeException(
sprintf("Core migration %s failed: %s", $filename, $migrationError->getMessage()),
0,
$migrationError
);
}
$totalApplied++;
$appliedFilenames[] = $filename;
}
return [
'ok' => true,
'applied' => $totalApplied,
'skipped_empty' => $skippedEmpty,
'total_files' => count($files),
'applied_filenames' => $appliedFilenames,
];
}
/**
* Inspect applied vs. pending migrations without running anything.
*
* @return array{applied: list<string>, pending: list<string>}
*/
public function status(): array
{
$this->repository->ensureTrackingTable();
$files = $this->discoverFiles();
$appliedMap = $this->repository->getAppliedFilenames();
$applied = [];
$pending = [];
foreach ($files as $file) {
$filename = basename($file);
if (isset($appliedMap[$filename])) {
$applied[] = $filename;
} else {
$pending[] = $filename;
}
}
sort($applied);
sort($pending);
return ['applied' => $applied, 'pending' => $pending];
}
/**
* @return list<string> Absolute paths of `*.sql` files in updates dir, sorted alphabetically.
*/
private function discoverFiles(): array
{
if (!is_dir($this->updatesPath)) {
return [];
}
$files = glob($this->updatesPath . '/*.sql');
if ($files === false || count($files) === 0) {
return [];
}
sort($files);
return $files;
}
}

8
db/init/init.sql
View File

@@ -465,6 +465,14 @@ CREATE TABLE IF NOT EXISTS `module_migrations` (
UNIQUE KEY `uq_module_migration` (`module_id`, `filename`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
CREATE TABLE IF NOT EXISTS `core_migrations` (
`id` INT UNSIGNED NOT NULL AUTO_INCREMENT,
`filename` VARCHAR(255) NOT NULL,
`applied_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (`id`),
UNIQUE KEY `uq_core_migration` (`filename`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
CREATE TABLE IF NOT EXISTS `user_api_tokens` (
`id` INT UNSIGNED NOT NULL AUTO_INCREMENT,
`uuid` CHAR(36) NOT NULL,

10
db/updates/2026-04-29-core-migrations-table.sql Normal file
View File

@@ -0,0 +1,10 @@
-- Tracking table for `bin/console db:migrate` (the new CLI that applies
-- db/updates/*.sql idempotently for existing installs). Identical DDL to the
-- one in db/init/init.sql; included here for installs that predate the table.
CREATE TABLE IF NOT EXISTS `core_migrations` (
`id` INT UNSIGNED NOT NULL AUTO_INCREMENT,
`filename` VARCHAR(255) NOT NULL,
`applied_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (`id`),
UNIQUE KEY `uq_core_migration` (`filename`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

2
docs/howto-erste-aenderung.md
View File

@@ -38,7 +38,7 @@ Ein neuer Entwickler soll den ersten Change strukturiert und reproduzierbar umse
3. Optional Service/Repository ergänzen, Instanziierung über `app(...)`/Factory-Standards
4. `docs/openapi.yaml` aktualisieren
5. `/docs/reference-api.md` mit Beispiel aktualisieren
6. Bei neuen Berechtigungen: `PermissionService` + `init.sql` synchron halten, für Bestandsumgebungen idempotentes SQL-Update in `db/updates/*.sql` bereitstellen
6. Bei neuen Berechtigungen: `PermissionService` + `init.sql` synchron halten, für Bestandsumgebungen idempotentes SQL-Update in `db/updates/*.sql` bereitstellen — wird automatisch von `bin/console db:migrate` (bzw. `module:sync`) angewendet
### Done-Kriterien

17
docs/howto-fehlerbehebung.md
View File

@@ -1,6 +1,21 @@
# Fehlerbehebung
Letzte Aktualisierung: 2026-03-14
Letzte Aktualisierung: 2026-04-29
## Schema scheint veraltet nach `git pull`
### Symptom
Nach einem Pull schlagen Queries fehl, weil eine Spalte/Tabelle fehlt — oder der Doctor meldet inkonsistentes Schema.
### Lösung
```bash
docker compose exec php php bin/console db:migrate --status # zeigt was fehlt
docker compose exec php php bin/console module:sync # wendet alles an (db:migrate + module:migrate + ...)
```
`db:migrate` wendet idempotente Updates aus `db/updates/*.sql` an und trackt sie in `core_migrations`. Auch nach manuellem `mariadb < db/updates/...sql` sicher: jeder Lauf ist idempotent.
## App reagiert nicht wie erwartet

24
docs/reference-cli-commands.md
View File

@@ -26,13 +26,13 @@ php bin/console <command> --help
### module:sync
Fuehrt den vollstaendigen Modul-Runtime-Sync aus: `migrate` → `permissions-sync` → `build` → `assets-sync`.
Fuehrt den vollstaendigen Runtime-Sync aus: `db-migrate` → `migrate` → `permissions-sync` → `build` → `assets-sync`.
```bash
docker compose exec php php bin/console module:sync
```
Noetig nach jeder Aenderung an Modulen, Manifesten, Routen oder `APP_ENABLED_MODULES`.
Noetig nach jeder Aenderung an Modulen, Manifesten, Routen oder `APP_ENABLED_MODULES` — und nach jedem `git pull`, der Schema-Updates unter `db/updates/*.sql` mitbringt.
Falls `web/index.php` den Fehler "Module runtime is stale" wirft, ist dieser Befehl die Loesung.
@@ -42,6 +42,26 @@ Maschinenlesbar:
docker compose exec php php bin/console module:sync --format=json
```
### db:migrate
Wendet idempotente Core-Schema-Updates aus `db/updates/*.sql` an. Angewendete Files werden in der Tabelle `core_migrations` getrackt; jeder Lauf wendet nur neu hinzugekommene Files an.
Jede `db/updates/*.sql` MUSS idempotent sein (`CREATE TABLE IF NOT EXISTS`, `INSERT … ON DUPLICATE KEY UPDATE`, etc.) — Erstlauf gegen ein bereits bestehendes Schema ist damit ein No-op.
```bash
docker compose exec php php bin/console db:migrate
```
`module:sync` ruft den Befehl als ersten Schritt automatisch auf. Direktaufruf nuetzlich, wenn nur DB-Updates gewuenscht sind ohne Module-Build.
Status-Anzeige (kein Schreibzugriff):
```bash
docker compose exec php php bin/console db:migrate --status
```
Listet `applied:` und `pending:` separat — nuetzlich beim Debugging veralteter Schemata.
### module:migrate
Wendet ausstehende SQL-Migrationen aus aktiven Modulen an.

30
phpstan-baseline.neon
View File

@@ -2184,36 +2184,6 @@ parameters:
count: 1
path: tests/Console/ConsoleApplicationTest.php
-
message: '#^Public property "MintyPHP\\Tests\\Console\\FakeModuleRunner\:\:\$deactivateConfirm" is never used$#'
identifier: public.property.unused
count: 1
path: tests/Console/ModuleCommandsTest.php
-
message: '#^Public property "MintyPHP\\Tests\\Console\\FakeModuleRunner\:\:\$deactivateDryRun" is never used$#'
identifier: public.property.unused
count: 1
path: tests/Console/ModuleCommandsTest.php
-
message: '#^Public property "MintyPHP\\Tests\\Console\\FakeModuleRunner\:\:\$deactivateModuleId" is never used$#'
identifier: public.property.unused
count: 1
path: tests/Console/ModuleCommandsTest.php
-
message: '#^Public property "MintyPHP\\Tests\\Console\\FakeModuleRunner\:\:\$deactivateResult" is never used$#'
identifier: public.property.unused
count: 1
path: tests/Console/ModuleCommandsTest.php
-
message: '#^Public property "MintyPHP\\Tests\\Console\\FakeModuleRunner\:\:\$runtimeSyncResult" is never used$#'
identifier: public.property.unused
count: 1
path: tests/Console/ModuleCommandsTest.php
-
message: '#^Public constant "MintyPHP\\Tests\\Service\\Access\\TestMultiDependencyPolicy\:\:ABILITY" is never used$#'
identifier: public.classConstant.unused

99
tests/Console/CoreCommandsTest.php Normal file
View File

@@ -0,0 +1,99 @@
<?php
namespace MintyPHP\Tests\Console;
use MintyPHP\Console\Commands\Database\MigrateCommand;
use PHPUnit\Framework\TestCase;
final class CoreCommandsTest extends TestCase
{
public function testDbMigrateSuccessOutputAndExitCode(): void
{
$runner = new FakeModuleRunner();
$runner->dbMigrateResult = [
'command' => 'db:migrate',
'status' => 'ok',
'exit_code' => 0,
'vendor_warnings_ignored' => 0,
'message' => 'db-migrate: applied 3 migration(s).',
];
$command = new MigrateCommand($runner);
ob_start();
$exitCode = $command->execute([], []);
$output = (string) ob_get_clean();
self::assertSame(0, $exitCode);
self::assertStringContainsString('db-migrate: applied 3 migration(s).', $output);
}
public function testDbMigrateFailureWritesToStderrAndReturnsNonZero(): void
{
$runner = new FakeModuleRunner();
$runner->dbMigrateResult = [
'command' => 'db:migrate',
'status' => 'failed',
'exit_code' => 1,
'vendor_warnings_ignored' => 0,
'message' => 'db-migrate: failure: Core migration foo.sql failed: SQLSTATE[42S02]',
];
$command = new MigrateCommand($runner);
ob_start();
$exitCode = $command->execute([], []);
ob_end_clean();
self::assertSame(1, $exitCode);
}
public function testDbMigrateStatusListsAppliedAndPending(): void
{
$runner = new FakeModuleRunner();
$runner->dbMigrateStatusResult = [
'command' => 'db:migrate --status',
'applied' => [
'2026-02-23-tenant-scope-global.sql',
'2026-03-13-seed-default-roles.sql',
],
'pending' => [
'2026-04-29-core-migrations-table.sql',
],
];
$command = new MigrateCommand($runner);
ob_start();
$exitCode = $command->execute([], ['status' => true]);
$output = (string) ob_get_clean();
self::assertSame(0, $exitCode);
self::assertStringContainsString('2 applied, 1 pending', $output);
self::assertStringContainsString('2026-02-23-tenant-scope-global.sql', $output);
self::assertStringContainsString('2026-04-29-core-migrations-table.sql', $output);
self::assertStringContainsString("applied:\n", $output);
self::assertStringContainsString("pending:\n", $output);
}
public function testDbMigrateStatusHandlesEmptyLists(): void
{
$runner = new FakeModuleRunner();
$runner->dbMigrateStatusResult = [
'command' => 'db:migrate --status',
'applied' => [],
'pending' => [],
];
$command = new MigrateCommand($runner);
ob_start();
$exitCode = $command->execute([], ['status' => true]);
$output = (string) ob_get_clean();
self::assertSame(0, $exitCode);
self::assertStringContainsString('0 applied, 0 pending', $output);
self::assertStringContainsString("applied:\n (none)", $output);
self::assertStringContainsString("pending:\n (none)", $output);
}
}

32
tests/Console/ModuleCommandsTest.php
View File

@@ -19,6 +19,7 @@ final class ModuleCommandsTest extends TestCase
'vendor_warnings_ignored_total' => 2,
'duration_ms' => 88,
'steps' => [
'db-migrate' => ['status' => 'ok', 'exit_code' => 0, 'vendor_warnings_ignored' => 0],
'migrate' => ['status' => 'ok', 'exit_code' => 0, 'vendor_warnings_ignored' => 0],
'permissions-sync' => ['status' => 'ok', 'exit_code' => 0, 'vendor_warnings_ignored' => 1],
'build' => ['status' => 'ok', 'exit_code' => 0, 'vendor_warnings_ignored' => 0],
@@ -41,6 +42,7 @@ final class ModuleCommandsTest extends TestCase
self::assertSame('ok', $decoded['status']);
self::assertSame(0, $decoded['exit_code']);
self::assertArrayHasKey('steps', $decoded);
self::assertArrayHasKey('db-migrate', $decoded['steps']);
self::assertArrayHasKey('migrate', $decoded['steps']);
self::assertArrayHasKey('assets-sync', $decoded['steps']);
}
@@ -78,6 +80,9 @@ final class ModuleCommandsTest extends TestCase
}
}
/**
* @api Test fixture — public properties are mutated by test cases across files.
*/
final class FakeModuleRunner implements ModuleRunnerInterface
{
/** @var array<string, mixed> */
@@ -88,6 +93,7 @@ final class FakeModuleRunner implements ModuleRunnerInterface
'vendor_warnings_ignored_total' => 0,
'duration_ms' => 0,
'steps' => [
'db-migrate' => ['status' => 'ok', 'exit_code' => 0, 'vendor_warnings_ignored' => 0],
'migrate' => ['status' => 'ok', 'exit_code' => 0, 'vendor_warnings_ignored' => 0],
'permissions-sync' => ['status' => 'ok', 'exit_code' => 0, 'vendor_warnings_ignored' => 0],
'build' => ['status' => 'ok', 'exit_code' => 0, 'vendor_warnings_ignored' => 0],
@@ -96,6 +102,22 @@ final class FakeModuleRunner implements ModuleRunnerInterface
'message' => 'ok',
];
/** @var array<string, mixed> */
public array $dbMigrateResult = [
'command' => 'db:migrate',
'status' => 'ok',
'exit_code' => 0,
'vendor_warnings_ignored' => 0,
'message' => 'db-migrate: all updates already applied.',
];
/** @var array<string, mixed> */
public array $dbMigrateStatusResult = [
'command' => 'db:migrate --status',
'applied' => [],
'pending' => [],
];
/** @var array<string, mixed> */
public array $deactivateResult = [
'command' => 'module:deactivate',
@@ -109,6 +131,16 @@ final class FakeModuleRunner implements ModuleRunnerInterface
public bool $deactivateConfirm = false;
public bool $deactivateDryRun = false;
public function dbMigrate(): array
{
return $this->dbMigrateResult;
}
public function dbMigrateStatus(): array
{
return $this->dbMigrateStatusResult;
}
public function migrate(): array
{
return [