Weave Code
Laravel Event Sourcing Laravel Package
patchlevel/laravel-event-sourcing
Laravel event sourcing with aggregates, projectors, reactors, snapshots, and a database-backed event store. Includes artisan tooling, testing helpers, and a clean API for modeling domain events in Laravel applications.
An event sourcing laravel package, complete with all the essential features, powered by the reliable Doctrine ecosystem and focused on developer experience.
Frequently asked questions about Laravel Event Sourcing
- What is patchlevel/laravel-event-sourcing used for?
- It is an opinionated event-sourcing and CQRS layer for Laravel applications. You model domain behaviour with aggregate roots that record events, persist those events in an event store, and derive read models through projections while reactors handle side effects. It fits domains where an auditable event log, replay, or temporal queries are real requirements, such as ledgers, order lifecycles, and approval workflows.
- How do I install patchlevel/laravel-event-sourcing in a Laravel app?
- Install it with Composer using composer require patchlevel/laravel-event-sourcing. Then publish the package configuration and any event store migrations, run php artisan migrate, and point the config at your chosen store connection. Because the package registers its services through a service provider, no manual wiring should be required after publishing config.
- Which Laravel and PHP versions does this package support?
- The package targets Laravel applications built on supported Illuminate components, but exact constraints move between releases. Check the require block in the package's composer.json against your pinned Laravel minor and PHP version before adopting it. If you maintain an internal Laravel skeleton, confirm compatibility in a branch first rather than assuming the constraint matches your lock file.
- Can I use my own event store implementation instead of the default one?
- Yes. The event store is pluggable, and the package ships a database-backed store built on Laravel's database abstractions. Version 1.5.0 added first-party Illuminate-based store implementations, which reduces reliance on bespoke drivers. If you implement the store contract yourself, verify the interface surface against the release you install, since minor releases can still touch that contract.
- What is the difference between a projection and a reactor?
- A projection listens to stored events and writes derived read models, such as query-friendly tables or search indexes. A reactor also listens to events but is intended for side effects like sending mail, dispatching jobs, or calling external services. Use projections when you need to rebuild state from the event log, and reactors when the work is a consequence rather than a queryable view.
- Do I need to flush the cache when upgrading to 1.5.0?
- Treat a cache flush as mandatory on deploy for 1.5.0. The release adapts to hashed metadata cache keys, so entries written under the previous key scheme become unreachable at best, and stale metadata is a correctness risk on a hydration-sensitive path. Adding a cache purge step to your deployment pipeline is cheaper than debugging projector replay after the fact.
- Is metadata caching opt-in, and how is it invalidated on replay?
- Metadata caching is a performance feature aimed at replay and projection throughput, with cache keys derived from a hash. Whether it is enabled per store and what the documented invalidation contract is on projector replay and aggregate rebuild should be confirmed against the package docs for your exact version. Until that is verified in your own environment, plan for explicit cache purges during deploys and after large replays.
- How do snapshots work with aggregates in this package?
- Snapshots let an aggregate be rehydrated from a stored state plus the events recorded after it, rather than replaying the full event stream. That keeps rebuild times bounded as streams grow, at the cost of an extra persistence path and more moving parts during schema changes. They are most useful for long-lived aggregates with high event volume, not for short streams.
- How do I test aggregates and projections built with this package?
- The package includes testing helpers so you can assert the events an aggregate records after invoking a behaviour, without touching a real database. Projections are best tested by feeding known events and asserting the resulting read model rows, which keeps them fast and deterministic. Run these in your normal PHPUnit or Pest suite and add an integration test against the real store for the persistence path.
- When should I avoid this package, and what are the alternatives?
- Avoid it for CRUD-first applications where an event log is not a domain requirement, because adopting event sourcing is an architectural commitment rather than a drop-in library swap. If you do need it, comparable options include spatie/laravel-event-sourcing for a more Laravel-native approach, event-sauce/event-sauce for a framework-agnostic core, and prooph for a broader CQRS stack. Evaluate them against your need for snapshots, Illuminate-backed persistence, and testing ergonomics.
Weaver
How can I help you explore Laravel packages today?