Laravel Event Sourcing Laravel Package

Technical Evaluation

Architecture fit. patchlevel/laravel-event-sourcing is an opinionated event-sourcing/CQRS layer for Laravel: aggregates, stored domain events, projectors and reactors, wired through a service provider. It fits applications where an auditable event log and derived read models are a domain requirement (ledgers, order lifecycles, approval workflows, anything needing temporal queries or replay). It does not fit CRUD-first applications, and adopting it is an architectural commitment, not a library swap — the 1.5.0 changes do not alter that calculus.

What 1.5.0 actually delivers. Six merged PRs, two contributors, no issues closed. Three substantive enhancements:

• Metadata caching (#46, #57) — cached metadata for stored events, with cache keys derived from a hash. This is a performance feature aimed at replay/projection throughput.
• Illuminate-based store implementations (#39) — first-party store implementations built on Laravel's database/queue abstractions rather than package-specific drivers. This reduces the surface area we own and improves fit with standard Laravel infrastructure.
• StackHydrator support (#51) — compatibility with the stack-based hydrator pattern and its extensions, i.e. composable event/aggregate hydration. Relevant only if we need custom hydration chains.
• Docs migrated from mkdocs to patchlevel.dev (#43) — no runtime impact, but it invalidates any internal links, onboarding material, or ADR references pointing at the old docs.

Technical risk. Low-to-moderate, and concentrated in one place: #57 "adapt to the hashed metadata cache keys" implies the cache key format changed within the release. On upgrade, previously cached metadata entries become unreachable (benign) or, if a key collides with an earlier scheme, could surface stale metadata (not benign). Treat cache-flush-on-deploy as mandatory. The cache also introduces a new failure domain between the event store and hydration — a correctness-sensitive path. #39 is more consequential architecturally: introducing Illuminate-backed stores means a persistence/configuration decision that should be made deliberately, not inherited by default.

Key questions for the maintainers / our spike.

1. Is metadata caching opt-in per store, and what is the documented invalidation contract on projector replay and aggregate rebuild?
2. Does the hashed key change require an explicit cache purge during upgrade, and is that called out in the upgrade guide?
3. Which store is the default in 1.5.0, and what is the migration path between the legacy store and the Illuminate implementations — including schema differences?
4. Are there BC breaks in the store interface for anyone who wrote a custom store (this is a minor release, so officially no, but #39 touches the contract surface)?
5. Does StackHydrator support require changes to existing aggregates/projectors, or is it additive?

Integration Approach

Stack fit. Requires a Laravel application on a currently supported version (confirm the constraint in composer.json against our pinned framework minor). Dependencies are light — larastan bumped to 3.10.0 is dev-only. The Illuminate store work means we can now run against the database and cache backends we already operate instead of bespoke drivers, which is the single biggest integration win in this release.

Migration path. Nothing in the notes is flagged as breaking, so the path is a routine minor bump: update the constraint to ^1.5, composer update patchlevel/laravel-event-sourcing, run the existing test suite, then flush the metadata cache as part of the deploy. The larger migration decision is orthogonal to the version bump: if we choose to move onto the Illuminate store implementations, that is a data-migration project, not a dependency upgrade — plan it separately with a dual-write or replay-based cutover and a verified read-model rebuild.

Compatibility. Verify three things before merge: (a) our cache driver supports the key operations used (tagging if relied upon — Redis/Memcached differ from file/array); (b) any custom store or hydrator implementations still satisfy the interfaces; (c) doc links in our ADRs and runbooks are repointed to patchlevel.dev.

Sequencing.

1. Spike branch: bump to 1.5.0 with metadata caching disabled; confirm green build and unchanged projection output.
2. Enable metadata caching in staging; run a full projector replay and diff read models against the pre-change snapshot.
3. Load-test replay with and without the cache to quantify the gain — if it's negligible at our event volume, defer enabling it and take the upgrade for the security/maintenance value only.
4. Evaluate #39 (Illuminate stores) as a separate initiative with its own ADR.
5. Adopt StackHydrator only if a concrete hydration requirement exists; otherwise treat as available, not adopted.

Operational Impact

Maintenance. Two contributors on this release, with one (DanielBadura) authoring five of six PRs — a clear bus-factor signal. Renovate automation is present, which is a positive health indicator, but dependency updates arriving via bot PRs need a human reviewer with context. Budget for us being the de facto maintainers of our integration layer. The docs move to patchlevel.dev means our internal runbooks must be updated or they will silently rot.

Support. Community-supported OSS with no commercial SLA. Escalation path is GitHub issues/PRs; if event sourcing is load-bearing for revenue flows, we need an internal owner who can read the package source and patch it. Do not adopt on the assumption that upstream will respond on our timeline.

Scaling. The metadata cache is the scaling feature here — it targets repeated metadata reads during hydration and replay, which is where event-sourced systems typically get expensive. Confirm the cache is shared across app instances (Redis/Memcached, not array/file) or each node warms independently and the benefit largely evaporates. The Illuminate stores should improve scaling ergonomics by letting us use managed DB infrastructure and standard connection pooling rather than custom drivers.

Failure modes.

• Cache unavailable — hydration falls back to the store or fails outright; determine which, and whether that is a latency event or an outage. Test by killing the cache mid-replay.
• Stale metadata — the highest-severity risk: silently wrong aggregate state is far worse than an exception. Mitigate with cache purge on deploy, TTLs where correctness permits, and a post-deploy reconciliation check on a sample of aggregates.
• Store misconfiguration after #39 — if Illuminate stores are enabled with the wrong connection, events could land in an unexpected database. Enforce config review and an environment assertion at boot.
• Replay cost — enabling the cache changes replay performance characteristics; capacity-plan replays explicitly rather than assuming the old profile.

Ramp-up. The 1.5.0 surface itself is small and learnable in a day. The real ramp is event sourcing as a paradigm — aggregates, projector idempotency, replay discipline, versioning of events. Assume two to three weeks before a mid-level engineer is productive and safe to modify projectors unsupervised. Pair that with a written internal standard covering cache configuration, replay procedure, and store selection, so the 1.5.0 decisions are recorded rather than rediscovered at the next minor release.