Laravel Event Sourcing Laravel Package

Getting Started

As of 1.5.0, start by installing the package with Composer and reading the docs at patchlevel.dev — the project moved docs from mkdocs to that site in this release. Publish any package config and migrations, then configure your event store connection.

The quickest first use case is a small aggregate + projector flow:

1. Define an aggregate that records domain events.
2. Persist those events through the configured event store.
3. Build a projector that updates a read model from those events.
4. Replay the projection to verify the read model can be rebuilt.

If you are on a standard Laravel database stack, evaluate the new Illuminate-based store implementations first; they reduce the need for custom store wiring. Leave metadata caching and custom hydration off until the basic write/project/replay loop works.

Implementation Patterns

• Write through aggregates, read through projections. Keep business invariants in aggregates/events and keep projectors focused on denormalized read models. Reactors should handle side effects, not projection state.
• Prefer Illuminate stores for normal Laravel apps. The 1.5.0 release adds Illuminate-based store implementations, so teams using MySQL/PostgreSQL/SQLite can often use native Laravel connections and migrations instead of maintaining a custom store adapter.
• Use metadata caching for hot metadata reads. 1.5.0 adds metadata cache support and adapts to hashed metadata cache keys. Enable it when metadata lookups are repeated often, but treat the cache as an implementation detail rather than something to inspect or manipulate directly.
• Use StackHydrator for payload evolution. If event payloads need versioning, custom serialization, or compatibility handling, compose hydrators in the intended order and add extensions deliberately. Cover old and new event shapes in replay tests.
• Keep projectors idempotent. Replays are a normal operational task. Projectors should tolerate repeated events or provide a clean reset/rebuild path.
• Configure via Laravel conventions. Put store connection, cache store, queue, and hydrator choices in config/environment rather than hard-coding them in domain code.
• Test replay, not just writes. A useful integration test records events, runs the projector, resets the read model, replays, and asserts the same final state.

Gotchas and Tips

• Do not depend on raw metadata cache keys. 1.5.0 switches to hashed metadata cache keys. Use the package APIs and clear the metadata cache after upgrading or changing metadata serialization/config.
• Clear caches after deployment. Run your normal Laravel config/cache clear steps. If you enabled metadata caching before upgrading, old cache entries may be orphaned or stale.
• Check store migrations and connection settings. When adopting Illuminate-based stores, confirm the configured database connection, table names, and migrations match your environment. Test SQLite if you use it locally and MySQL/PostgreSQL in production.
• Hydrator order matters. With StackHydrator and extensions, register hydrators in the documented order and add tests for historical events. A hydrator change can break replay even when new writes work.
• Avoid side effects during replay. Reactors, mail, jobs, and external API calls should not fire while rebuilding projections. Use replay-aware guards or separate rebuild paths.
• Treat 1.5.0 as a minor upgrade, but still verify. The release is feature-focused and does not list breaking changes. Run the full event write/project/replay path and clear caches before shipping.
• Use extension points intentionally. Custom stores, hydrators, metadata cache stores, and metadata enrichers are integration points; keep them thin and covered by tests so package upgrades remain low-risk.
• Debug with event identity. Log aggregate IDs, event IDs, and projection names when diagnosing replay or cache issues. Inspect stored events through package APIs where possible rather than relying only on raw table queries.