Weave Code
Laravel Event Sourcing Laravel Package
spatie/laravel-event-sourcing
spatie/laravel-event-sourcing is the entry point for event sourcing in Laravel, helping you set up aggregates, projectors, and reactors. Great for apps that need to make decisions based on the past, meet auditing requirements, or support future reporting.
spatie/laravel-event-sourcing is the entry point for getting started with event sourcing in Laravel. It helps you set up aggregates, projectors, and reactors, so your app can make decisions based on the past, keep full audit trails, and collect data for future reporting.
- Store and replay domain events via aggregates
- Build read models with projectors
- Handle side effects with reactors
- Seamless Laravel integration
- Example apps and in-depth docs
Frequently asked questions about Laravel Event Sourcing
- What is spatie/laravel-event-sourcing and when should I use it?
- It is Spatie's entry-point package for event sourcing in Laravel, giving you aggregates for the write model, projectors for read models, and reactors for side effects, backed by a stored_events persistence layer with migrations, artisan generators, and replay commands. The README names three drivers that justify it: an app that must make decisions based on past events, auditing requirements where the reason for a state matters as much as the state itself, and expected future reporting where you do not yet know which data to collect. If your application is plain CRUD where current state is the whole story, event sourcing is usually the wrong fit.
- Which Laravel and PHP versions does spatie/laravel-event-sourcing support?
- The package targets Laravel 10 through 13 on PHP 8.2 and above, and ships with a service provider, publishable config, and migrations for stored_events, projections, and snapshots. Laravel 13 and PHP 8.5 support landed in 7.14.0, and Symfony 8 support arrived in 7.12.3. It expects a MySQL or Postgres database with JSON column support, and Redis plus Horizon if you plan to run reactors asynchronously.
- Do I have to rewrite my existing Laravel application to adopt event sourcing?
- No, and you should not try to. The package's key architectural affordance is the hybrid option: projectors write to ordinary Eloquent tables, so your existing controllers, API contracts, and read paths keep working unchanged while the write path for one bounded context moves to an aggregate. Introduce a single aggregate in a single bounded context first, with a projector maintaining the tables your app already reads, and let the event stream become the authoritative write log alongside them.
- What is the difference between a projector and a reactor?
- A projector listens to events and writes to your read model, typically Eloquent tables that your application queries, so projectors must be idempotent because events can be replayed. A reactor performs side effects such as sending mail, calling APIs, or dispatching jobs, and it is the piece you usually run queued rather than synchronously. Choosing sync versus queued reactors is a business decision about consistency: synchronous gives immediate effects at the cost of latency and coupled failures, queued gives throughput at the cost of eventual consistency.
- How do I migrate from laravel-event-projector to laravel-event-sourcing?
- The migration is close to mechanical because the new package supersedes the old one with essentially the same API, and a documented upgrade guide walks you through it. Treat it as a normal dependency bump rather than a rewrite, but run your projector and reactor test suite against a fresh database before shipping. Confirm your Laravel and PHP versions satisfy the compatibility checklist first, since the new package requires Laravel 10 or newer and PHP 8.2 or newer.
- How does the package handle aggregate version conflicts?
- The package uses optimistic concurrency: an aggregate records its version, and a write based on a stale version will fail rather than silently overwrite. That is deliberate, but it means the conflict has to be handled somewhere, and that somewhere is usually your UI, which needs a defined behaviour such as retry, refresh, or reject with a message. Decide the user-facing story for conflicts before you go live, because the package cannot make that decision for you.
- Is it safe to change event payloads after events are written in production?
- Stored event payloads are your system of record and are serialized through Symfony Serializer, so changing how events serialize is effectively changing a data format. The changelog shows this boundary producing regressions in patch releases, including metadata leaking into event_properties in 7.12.5, time conversion in json_encode in 7.11.1, an attribute-reader swap in 7.15.0, and Ignore attribute conflicts in 7.12.9. Historic events must remain readable forever, so establish an upcasting convention and pin your versions carefully before the first production write.
- How do I test aggregates, projectors, and reactors with this package?
- Because the package ships with artisan generators and replay commands, the practical testing pattern is to build aggregates and projectors against a fresh in-memory or test database, replay the recorded events, and assert the resulting projections. The three Larabank example apps, traditional, projector-only, and aggregate-plus-projector, show the same domain implemented at each level and are useful as reference test suites. Note that 7.12.2 changed behaviour so handling continues after an exception, which is good for throughput but dangerous if your tests or alerting assume exceptions always surface.
- What should I plan for in production: event volume, replays, and backups?
- Answer three questions before approval: expected event volume per day, retention policy, and the acceptable duration of a full replay in minutes, since that replay is your recovery path. Decide how many read models exist and which consumers depend on them, and assign clear operational ownership for the event store, including backups, point-in-time recovery, and a written replay runbook. Serialization durability is the largest technical risk, so treat serializer upgrades as data migrations rather than routine dependency bumps.
- Is spatie/laravel-event-sourcing actively maintained and what are the alternatives?
- Yes, it is a first-party-quality Spatie package under the MIT license with a healthy and responsive release cadence, though there is no LTS and no commercial SLA, and maintenance is concentrated in one organisation. Support runs through GitHub issues plus a paid event sourcing in Laravel course, so budget accordingly if your team needs guaranteed response times. If you want a framework-agnostic option, EventSauce is the common alternative, but you lose the Laravel-native migrations, generators, and replay commands that make this package quick to adopt here.
Weaver
How can I help you explore Laravel packages today?