Refresher Laravel Package

Product Decisions This Supports

• Test-suite latency → CI spend and developer throughput. The package replaces per-test migrate:fresh with a cached snapshot restore. Decision to make: is database setup a measurable line item in CI minutes and local test wait time? Instrument first (migration + seed time × runs/day × engineers), then decide.
• Build vs buy for internal snapshot tooling. Teams often hand-roll "dump the DB after migrations, reload it between tests." This is that, maintained, with Laravel-core parity. Buying is defensible unless you have non-standard drivers or schema-mutating tests.
• Broadening integration-test coverage. Faster DB resets lower the cost of real-database tests, which supports a roadmap decision to reduce mocking in favour of integration coverage for critical paths (payments, permissions, multi-tenant isolation).
• Adoption risk re-scored by v1.1.0. The seeding bug fix is the headline: previously a suite using $seed, $seeder, or #[Seed]/#[Seeder] could silently run against an unseeded database — i.e. false-green tests. That is exactly the class of defect that kills trust in a test-infrastructure dependency. If an earlier evaluation was blocked on correctness grounds, re-run it; the trait now overrides only migrateDatabases() and passes migrateFreshUsing() through, so seeding, $dropViews, $dropTypes, and core's in-memory PDO cache behave as in RefreshDatabase.
• Standardization decision. LazilyRefreshesWithRefresher (new) and RefreshesWithRefresher are drop-in replacements for LazilyRefreshDatabase and RefreshDatabase. Migration cost is a trait swap, which means the decision can be made at team level without an architecture review — low blast radius, easily reversed.
• CI caching strategy. The snapshot key now covers migration paths registered via loadMigrationsFrom() (auto-discovered), seeders/factories when seeding, the driver, and migrate:fresh options — and is machine-independent, so a snapshot built on one runner validates on every other. That makes "persist the snapshot as a CI artifact / cache layer" a viable pipeline decision rather than a fragile one.
• Driver coverage as a scoping input. MariaDB (driver => mariadb) is now explicitly supported; SQLite WAL is checkpointed before snapshot and stale -wal/-shm files are removed on restore; MySQL restore now drops all tables and views first, matching migrate:fresh, so leftover branch-created or test-created tables no longer survive. This widens which services can adopt without caveats.

When to Consider This Package

Adopt when most of these hold:

• Database setup dominates test runtime — migrations plus seeding are a visible chunk of every run.
• The stack is Laravel 11/12/13 on PHP 8.3+ and Symfony 7.2 or 8. Note the constraint changes in v1.1.0: symfony/process moved from ^6.0|^7.0 to ^7.2|^8.0, and PHP simplified to ^8.3. For apps still on PHP 8.1/8.2 or Symfony 6, v1.1.0 is effectively a breaking bump — confirm the version floor before committing, or stay pinned to the prior release.
• The data layer is MySQL, MariaDB, or SQLite.
• The team already uses RefreshDatabase/LazilyRefreshDatabase and wants identical semantics rather than a new testing paradigm.
• There is a CI pipeline where snapshot reuse across runners pays for itself.

Look elsewhere when:

• Postgres is the primary database — not mentioned in this release; verify or exclude.
• Tests mutate schema at runtime (create tables in test bodies). MySQL restore now handles this by dropping everything first, but it is a persistent complexity signal and a recurring source of upstream bugs.
• Suites are small enough that migrate:fresh costs nothing measurable — the added indirection buys you nothing.
• You require commercially supported or multi-maintainer infrastructure dependencies. The php artisan about section now surfaces a support link, which suggests a support channel exists — validate its responsiveness before standardizing across many services.
• Security policy forbids password material in environment variables; the MySQL fix now passes the password via MYSQL_PWD rather than --password= (a genuine improvement: no CLI warning, not visible in the process list), but confirm it matches your policy.

How to Pitch It (Stakeholders)

For executives: This is a small, narrowly scoped dependency that removes repeated database setup from our test runs — the kind of change that shows up directly as lower CI spend and shorter waits for engineers. The v1.1.0 release is mainly a correctness release: it closes a gap where seeded test suites could run against an unseeded database and pass for the wrong reasons, and it fixes environment and driver handling (MySQL credentials, sockets, long dumps timing out at 60 seconds, SQLite WAL artifacts). Cost of adoption is one trait swap per test base class; cost of reversal is the same. Recommend a single-service pilot with before/after CI minutes.

For engineering: Two drop-in traits — RefreshesWithRefresher and the new LazilyRefreshesWithRefresher — mirroring core's RefreshDatabase and LazilyRefreshDatabase. The v1.1.0 work deliberately restores core parity by overriding only migrateDatabases() and forwarding migrateFreshUsing(), so seeding, $dropViews, $dropTypes, and core's own $migrated/PDO bookkeeping are untouched. Snapshot invalidation is now driven by a machine-independent key that includes loadMigrationsFrom() paths (auto-discovered), seed paths, driver, and migrate:fresh options — meaning stale-snapshot bugs from branch switches or new seeders should be rare, and CI-cached snapshots are portable between runners. Operationally there is now refresher:clear to nuke all cached snapshots, --fresh-options on refresher:snapshot, and a Refresher section in php artisan about for version and snapshot path.

Pilot plan to de-risk the buy decision: swap the trait in one service, assert seeding parity explicitly (a test that fails if the DB is empty), compare CI wall time on the same commit range, and verify the PHP/Symfony floor in composer.json before merge.