Refresher Laravel Package

Technical Evaluation

What it is: A Laravel test-suite utility that replaces RefreshDatabase / LazilyRefreshDatabase with snapshot-based database refresh. Instead of re-running migrations for every test, it snapshots a freshly migrated database once and restores it per test. Surfaces: RefreshesWithRefresher, LazilyRefreshesWithRefresher, php artisan refresher:snapshot, refresher:clear, --fresh-options, and a php artisan about panel.

Architecture fit: Very low intrusion. It is a require-dev-only package with no production runtime surface, no schema coupling, and no application-code changes beyond swapping one trait in the base TestCase. Critically, the trait now overrides only migrateDatabases() and passes migrateFreshUsing() through, so $seed/$seeder, #[Seed]/#[Seeder], $dropViews, and $dropTypes behave exactly as core RefreshDatabase does, and Laravel's own in-memory PDO cache and $migrated bookkeeping are left intact. From a TPM standpoint that is the key property: the framework contract is preserved rather than reimplemented, so behavioral drift risk is contained.

Integration feasibility: High for PHP 8.3+ / Symfony 7.2+ stacks on MySQL, MariaDB, or SQLite. The release narrows constraints (symfony/process ^7.2|^8.0, PHP ^8.3), which is good for Laravel 13/Symfony 8 apps but effectively locks out Symfony 6-era applications — that must be checked against our composer matrix before committing.

Technical risk: Medium-low, concentrated in two areas rather than spread. First, snapshot correctness — the top historical failure mode (stale snapshots, seed state not captured) is directly addressed: the key now covers loadMigrationsFrom() paths, seeders/factories when seeding, the driver, and the migrate:fresh options, and is machine-independent so a CI-cached snapshot matches across runners. Second, restore destructiveness — MySQL restore now drops every table and view first, matching migrate:fresh; this is correct but means any test relying on residual schema from another branch or a prior test will break. That is a latent bug being surfaced, not a regression, but it will produce red builds during rollout.

Key questions:

• Which suites currently seed? v1.0 silently ignored $seed/$seeder, so any green result on a seeded suite is untrustworthy and must be re-baselined, not just re-run.
• Does any test depend on schema or data created outside migrations? Those will fail on first restore and need individual triage.
• Where will snapshots live in CI, and is the cache keyed on the composer lockfile plus the new snapshot key? A snapshot that outlives a dependency bump is the residual stale-state risk.
• What is the measured wall-clock win on our slowest suite versus the added refresher:snapshot step? Without that number the business case is anecdotal.
• Who supports the package long-term? The about panel exposing a support link hints at external or commercial backing — we need an SLA and a bus-factor read before depending on it.

Integration Approach

Stack: Add as a dev dependency only. Target apps on Laravel 12/13, PHP 8.3+, Symfony 7.2/8.0. Confirm the correct driver value per environment — driver => mariadb is now distinct from mysql, and MariaDB users should set it explicitly. MySQL credentials via MYSQL_PWD and unix_socket support improve container and CI compatibility out of the box.

Migration path:

1. Inventory test suites and flag every suite that seeds — this release changes their behavior.
2. Pilot on the slowest, most isolated suite; swap RefreshDatabase → RefreshesWithRefresher (or LazilyRefreshDatabase → LazilyRefreshesWithRefresher) in that base TestCase only.
3. Generate a snapshot, run the suite, and compare pass/fail against the pre-pilot baseline.
4. Treat every newly failing test as a pre-existing hidden dependency on migration order, seed state, or cross-test schema leakage; triage individually rather than reverting wholesale.
5. Roll out suite by suite once the pilot's failure set is empty.

Compatibility: The constraint narrowing is the main compatibility gate — Symfony 6 apps cannot take this release, and staying on 1.0.x means carrying the seeding bug, which is a worse trade for any seeded suite. The destructive-restore change is semantics-compatible with migrate:fresh, so teams already writing tests against core behavior should be unaffected. Long dumps no longer hitting Symfony Process's 60-second timeout removes a hard ceiling on schema size.

Sequencing: Upgrade the package first and re-run seeded suites to expose the seeding fix before enabling any caching — otherwise stale snapshots and the seeding change confound each other. Then wire refresher:snapshot into CI ahead of the test job, key the cache on the machine-independent snapshot key plus the lockfile, add refresher:clear to cache-purge and dependency-bump jobs, and only then measure and publicize the speedup.

Operational Impact

Maintenance: Minimal steady-state burden. No production footprint, snapshots are ephemeral CI artifacts, and refresher:clear gives a blunt but effective invalidation lever. The countervailing signal is constraint churn: two dependency-floor narrowings in a single minor release indicates active development but also compatibility drift, so pin the version and review upgrades deliberately rather than floating.

Support: Blast radius is bounded — the escape hatch is reverting one trait, so a package failure degrades test runtime, not application behavior. That makes it a low-severity dependency from an incident standpoint. The open item is external support terms; the about support link should be resolved into an actual owner and SLA before this becomes load-bearing for CI.

Scaling: The win compounds with suite size and migration count: restore cost scales with table count, not migration count, so the largest suites benefit most. Machine-independent keying means parallel runners share one valid snapshot instead of each regenerating it, which is the difference between a CI cost saving and a CI cost increase. The WAL checkpoint and stale -wal/-shm cleanup on SQLite remove a class of flaky, hard-to-reproduce failures that would otherwise erode trust in the suite.

Failure modes:

• Stale snapshot — largely mitigated by the expanded key, but a snapshot surviving a lockfile change is still possible depending on cache configuration; key on both.
• Destructive restore — drops non-snapshot tables and views; correct, but will fail tests that depended on leaked state. Expect a one-time red-build wave during rollout.
• Missing snapshot — ensure the suite fails fast rather than silently falling back to full migration, otherwise runtime silently regresses and nobody notices.
• Seeding regression — fixed in this release, but historical results on seeded suites are suspect; re-baseline rather than assume.
• Parallel execution — confirm concurrent test workers handle snapshot file access safely before enabling on sharded CI.

Ramp-up: Low. One trait import per base TestCase plus a CI documentation note on snapshot generation and invalidation. Budget roughly half a day of engineering to pilot and validate, plus triage time for tests exposed by the seeding fix and the destructive restore — that triage, not the integration, is the real cost and should be scoped explicitly.