Skip to content

Laravel Bitemporal

Safe effective-dated and bitemporal relations for Laravel.

vusys/laravel-bitemporal provides first-class support for effective-dated and bitemporal Eloquent data — modelling facts that change over time, where the application needs to answer:

  • What was true on this business date?
  • What did the system believe was true on this business date at the time?
  • When did this value become effective, and when was a correction recorded?

The value is not a handful of query scopes. It is a custom temporal relation with safe write operations, range splitting, correction handling, point-in-time eager loading, and overlap prevention — so you can correct the past without destroying the previous state of knowledge or creating overlapping historical facts.

$product->prices()->correct(attributes: ['amount' => 12.00], validFrom: '2026-02-01');

Install

composer require vusys/laravel-bitemporal

PHP 8.4+, Laravel 11 / 12 / 13, and PostgreSQL, MySQL/MariaDB, or SQLite. The service provider is auto-discovered.

Start here

New to the package? Work through it in order:

  1. Concepts — valid time, recorded time, spells, anti-rows
  2. Installation — requirements, install, publishing config
  3. Defining models — the Bitemporal trait, relations, migrations, the generators
  4. Reading — point-in-time reads, spell predicates, entity scoping, eager loading
  5. Writing — change, correct, retract, end, supersede, backfill, concurrency, idempotency

Then reach for the rest as you need it:

See it in a real domain

Prefer to learn from a full worked example? Each of these follows one domain end to end — schema, writes, reads, and history — and leans on a different corner of the API:

  • Insurance & claims — recorded time and knownAt, retroactive endorsements, retractions, and knowledge diffs
  • Salary history — changeEffectiveFrom vs correct, reproducible payroll, optimistic concurrency, and backfilling
  • SaaS subscriptions — dimensions, temporal pivots, webhook-safe idempotent writes, and the as-of lens
  • Tax & regulatory rates — back-dated legislation, full restatements, and importing historical beliefs