Download the PHP package zachiler/laravel-cadence without Composer

Laravel Cadence

Run your Laravel application in accelerated time.

What It Does

Install the package, implement a tick handler, and run cadence:run. Your Eloquent models, queued jobs, and scheduled commands all operate against simulated time — hours pass in seconds. Observe your application behaving as if days or weeks have elapsed, all from a single Artisan command.

Quick Start

Register your scenario in config/cadence.php:

See Getting Started for the full walkthrough.

Configuration

How Time Works

Cadence uses Carbon's setTestNow() to shift all time-dependent code. During a simulation:

• now(), Carbon::now(), Date::now() — all return simulated time
• Eloquent timestamps (created_at, updated_at) — use simulated time automatically
• Queued job delays — evaluated against simulated time
• Scheduled commands — fire based on simulated cron evaluation

You do not need to call any special clock function in your application code. Standard Laravel time functions work as expected — the simulation makes them return simulated time instead of real time.

The Clock class (Cadence\Clock\Clock) is used internally by the runner. You can use Clock::now() or just now() — they return the same value during simulation.

Feature Highlights

Tick Scheduling DSL

Avoid time-checking boilerplate. The DSL handles interval tracking and day/time filtering:

Full reference

Handler Dependencies

Declare execution order through dependencies — the runner topologically sorts handlers before the first tick:

Full reference

Invariants & Breakpoints

Define conditions checked after every tick. Invariants assert correctness; breakpoints pause for inspection:

Full reference

Time-Series Metrics

Record named metrics from handlers for post-run analysis:

Full reference

Speed Schedules

Define multi-phase speed profiles for a single run:

Full reference

Tick Middleware

Wrap the entire tick cycle with before/after logic:

Full reference

Simulation Report

An automatic end-of-run summary with handler performance, event counts, and telemetry:

Full reference

And More...

• Warm-up periods — Separate bootstrap noise from measured results
• Simulation tagging — Attach metadata for filtering and comparison
• Auto-checkpoints — Automatic snapshots at simulated time intervals
• Handler telemetry — Automatic min/max/avg/p95 timing per handler
• Config hot-reload — Update handler config mid-simulation
• Quiet period skipping — Fast-forward through inactive periods
• Adaptive speed — Slow ticks run at 1:1 real time automatically
• Snapshot metadata hooks — Attach custom data to database snapshots
• Handler communication (TickBag) — Share data between handlers within a tick
• Clock-aware Eloquent scopes — Time-window queries that respect simulated time
• Dry-run mode — Preview without persisting data
• Reproducible simulations — Deterministic Faker output with --seed

Documentation

Requirements

• PHP 8.3+
• Laravel 12+
• MySQL or PostgreSQL recommended (see Database Drivers)
• Database queue driver (during simulation only)
• Cross-process cache driver (file, database, Redis, or Memcached)

Database Drivers

MySQL and PostgreSQL are recommended. SQLite works for quick local tests but causes lock contention under real simulation loads. See Database Drivers for configuration details and workarounds.

Safety

• Environment gating — cadence:run refuses to execute in environments not listed in allowed_environments
• Concurrent run prevention — checks for an already-running simulation before starting
• Queue driver enforcement — validates QUEUE_CONNECTION=database at runtime
• Cache driver validation — rejects array and null cache drivers that can't communicate across processes
• Tick timeout — max_tick_duration prevents a single tick from blocking the simulation indefinitely
• Clock cleanup — setTestNow is always reset in a finally block, even on crash
• Snapshot confirmation — cadence:restore requires interactive confirmation before replacing the database
• Dependency validation — circular and missing handler dependencies are caught at boot, not mid-simulation
• Dry-run isolation — --dry-run wraps the entire simulation in a transaction, rolling back all data changes

About

Laravel Cadence was co-authored by Zac Hiler and Claude. Learn more about the journey of building Laravel Cadence at zachiler.dev/projects/laravel-cadence.

License

MIT. See LICENSE.