Weave Code
Verbs History Laravel Package
hirethunk/verbs-history
Adds history tracking to hirethunk/verbs event-sourced Laravel applications, helping you keep an audit trail of model changes and inspect how state evolved over time through the Verbs event store.
At a glance
Frequently asked questions about Verbs History
- What is hirethunk/verbs-history used for?
- It adds history tracking and audit-trail capture to Laravel applications built with hirethunk/verbs. It stores state snapshots per aggregate on top of the Verbs event store so you can inspect how model state evolved over time. It is a companion package, not a standalone audit log.
- Can I use verbs-history without hirethunk/verbs installed?
- No. verbs-history is a companion package to hirethunk/verbs and inherits its aggregates, projectors, service provider, and replay conventions. Installing it means adopting Verbs event sourcing first. If you're on plain Eloquent, this is not a drop-in audit log.
- Which Laravel and PHP versions does verbs-history v0.6.0 support?
- The package targets Laravel 10/11-era applications on PHP 8.1 or newer and requires hirethunk/verbs ^0.6. Check your host app's Laravel and PHP matrix against Verbs v0.6 before committing. Because both packages are pre-1.0, confirm constraints during Composer resolution.
- How do I install and configure hirethunk/verbs-history?
- Require the package with Composer, let Laravel package auto-discovery register the service provider, then publish the config and migrations. Apply the history trait to the aggregates or models you want tracked. Mechanical setup is typically hours, but the real effort is the Verbs prerequisite and event-sourcing design.
- Is verbs-history v0.6.0 compatible with hirethunk/verbs 0.5.x?
- No. v0.6.0 is an alignment release that changes the core dependency constraint to verbs ^0.6. Any package or internal code pinned to Verbs 0.5.x will block the resolver or force a wider upgrade. Treat the Verbs 0.6 upgrade and this package bump as one coupled change.
- Will upgrading to verbs-history v0.6.0 break existing history rows?
- Possibly. Verbs 0.6 may alter event payloads, projector behavior, replay, or snapshot formats, and verbs-history consumes that state. History rows written under 0.5.x may not render or replay identically after the upgrade. Verify the upcaster and migration path for streams written on 0.5.x before upgrading production data.
- Can I backfill history for records created before installing verbs-history?
- Not automatically. History is only captured from the point you enable tracking forward, so pre-existing records have no history rows. Backfilling requires designing your own migration or replay approach against the Verbs event store. Plan for this before rollout if the audit trail must cover legacy data.
- Does verbs-history provide pruning or retention for history tables?
- There is no documented pruning, retention, or archival mechanism in the provided context. History tables are append-only and grow with every state change, not every business event, so storage and query cost surface months after launch. Plan an index strategy and a retention or archival policy for large aggregates.
- How do I test history tracking in a Verbs application?
- The package does not document a dedicated testing API, so test history through the Verbs testing helpers you already use for aggregates and projectors. Arrange state changes, invoke your aggregates, and assert the expected history rows were written. Include replay and upgrade scenarios because history rendering depends on Verbs payload and snapshot formats.
- Is hirethunk/verbs-history stable for production, and what are the alternatives?
- Both Verbs and verbs-history are 0.x, so SemVer gives no stability guarantee and minor bumps can break; the maintainer set is small with no vendor SLA, LTS, or published deprecation policy. It fits greenfield or evolving services where event sourcing is already chosen, not regulated systems with multi-year support windows. If you're not committed to Verbs, look at general Laravel audit-log packages instead of this companion.
Weaver
How can I help you explore Laravel packages today?