Verbs History Laravel Package

Getting Started

hirethunk/verbs-history extends Verbs — Thunk's event-sourcing package — with history/temporal querying on top of the event store, so you can ask "what did this aggregate look like at time T?" without hand-rolling replay logic.

Minimal setup:

composer require hirethunk/verbs-history
php artisan vendor:publish   # pick the verbs-history config + migration tags from the list
php artisan migrate

As of v0.6.0 the package tracks Verbs v0.6, so the two must be installed together at matching versions (see Gotchas).

Where to look first, in order:

1. config/verbs-history.php — retention/pruning knobs and the table names the package owns.
2. The published migrations — these tell you exactly what is persisted versus what is recomputed from the Verbs event store, which is the single most important thing to understand before you build on it.
3. The package's trait/interface that you attach to an aggregate or model — that is your entry point.

First use case: take an existing Verbs aggregate, attach the history behaviour to it, fire a couple of events, then read the history back in a Tinker session or a test. Confirm the ordering and the payload shape before wiring it into a UI — the shape of a history entry is what everything else in your app will depend on.

Implementation Patterns

Attach history at the aggregate, read it at the edge. Register the package's trait/interface on the aggregate that already extends Verbs' base class. Don't scatter history calls through controllers; expose a single query method (e.g. on a repository or query object) that returns history entries for an aggregate ID, and let the controller/Inertia/Livewire layer format them.

Timeline / audit UI. The canonical day-to-day use is an activity feed per record: $aggregate->history() (or the equivalent query builder) mapped into { happened_at, event, actor, changes } DTOs. Because the underlying data is derived from events, you get actor and correlation metadata for free — capture the authenticated user in your Verbs event metadata and the history view becomes an audit log with no extra bookkeeping.

Point-in-time reads. Use the package to reconstruct state at a timestamp for "view as of" features, dispute resolution, or showing a customer what changed since their last invoice. Keep these reads on a dedicated read path — never mutate off a historical snapshot; replay forward through Verbs if you need to correct something.

Integrate with Verbs' existing testing helpers. Verbs' event-store assertions still apply to the underlying events. Assert on the events you expect to be recorded and on the history entries the package derives from them, so a mismatch between the two surfaces in CI rather than in production.

Retention as a first-class concern. Decide early whether history is a permanent audit record or a rolling window. If rolling, wire the prune command into the scheduler at deploy time rather than retrofitting it once the table is large.

Gotchas and Tips

• Version lockstep is the headline issue for v0.6.0. This release exists solely to support Verbs v0.6. If you bump hirethunk/verbs to 0.6 without also bumping verbs-history to 0.6.0, you're on an unsupported combination. Pin both in composer.json and upgrade them in the same PR:

  "hirethunk/verbs": "^0.6",
  "hirethunk/verbs-history": "^0.6"
  

• Pre-1.0 means pre-1.0. Both packages are on 0.x, where a minor bump is a breaking change by semver convention. Treat every 0.x minor as a potential breaking change and read the Verbs changelog as well as this one — Verbs v0.6 almost certainly changed APIs the history package consumes, and those changes can leak into your code through the history layer even if your own aggregate code looks untouched.

• Migration ordering. The package's migrations must run after Verbs' own. If you have a long migration history, check php artisan migrate:status after upgrading — a stale published migration from an older verbs-history version is a common cause of confusing column/table errors. Republish and diff rather than assuming the old file is still correct.

• Don't assume history == event store. The package may persist derived rows alongside reading the event store. If you prune history rows, your events still exist and replay still works; if you prune the event store, history is gone. Never let a "clean up old records" task touch the Verbs tables.

• Debugging mismatches. When a history entry looks wrong, drop down a level: inspect the raw Verbs events for that aggregate ID first. Nearly every history bug is really an event that was recorded with unexpected metadata or in an unexpected order (e.g. events fired inside a DB transaction that rolled back partially).

• Extension points. The package is thin by design; before forking, check whether the config exposes what you need (table names, retention, serialisation). For anything richer — diffing, field-level change sets, human-readable labels — build a presenter layer on top of the history entries rather than patching the package, so upgrades stay cheap.

• CI signal. Add a smoke test that boots the app and reads history for one seeded aggregate. Version-skew bugs between Verbs and this package tend to be runtime binding/interface errors that only appear when the container resolves the history service — a test that actually touches it catches them at PR time.