Native Event Sourcing & Temporal Models Support for Laravel

[eslam-reda-div]

Summary

I'd like to propose introducing first-class, built-in Event Sourcing and Temporal Model support to Laravel's Eloquent ORM.

This feature would allow models to optionally operate in an event-sourced mode, enabling automatic versioning, time-travel queries, and auditability — without relying on third-party packages.

---

Motivation

Laravel currently stores only the latest state of a model.

When a model is updated:

$user->update(['balance' => 500]);

The previous state is lost unless developers manually implement:

• Audit logs
• History tables
• Custom event storage
• Or external packages

This becomes increasingly complex in domains where:

• Auditability is mandatory (finance, healthcare, compliance)
• State rollback is required
• Historical queries are needed
• Debugging production issues requires state replay

Event sourcing is a well-established architectural pattern, but Laravel does not natively support it.

This proposal aims to introduce optional, integrated support directly within Eloquent.

---

Proposed API

1. Aggregate Root Model

class BankAccount extends AggregateRoot
{
    public function deposit(int $amount)
    {
        $this->recordThat(new MoneyDeposited($amount));
    }

    protected function applyMoneyDeposited($event)
    {
        $this->balance += $event->amount;
    }
}

Instead of mutating state directly, changes are recorded as domain events.

---

2. Automatic Event Storage

Events would be stored in a dedicated event_store table:

| id | aggregate_type | aggregate_id | event_type | payload | version | created_at |

Each model becomes reconstructable via event replay.

---

3. Temporal Queries

BankAccount::at('2025-01-01')->find($id);

BankAccount::version(5)->find($id);

This would allow retrieving model state at a specific point in time or version.

---

4. Snapshot Support

To avoid replaying thousands of events:

config('temporal.snapshot_every') = 50;

Snapshots would be automatically created to optimize reconstruction performance.

---

5. Projection System (Optional Read Models)

class AccountProjection extends Projection
{
    public function onMoneyDeposited($event)
    {
        DB::table('accounts')
          ->increment('balance', $event->amount);
    }
}

This allows CQRS-style separation between write and read models.

---

Implementation Overview

The proposal would introduce:

New Core Classes

• AggregateRoot (extends Model)
• RecordsEvents trait
• EventStore repository contract
• Snapshot repository
• Temporal query builder extension

New Artisan Commands

php artisan event:replay
php artisan event:snapshot

Config File

config/temporal.php

---

Why Core and Not a Package?

While event sourcing can be implemented via packages, deep integration requires:

• Access to Eloquent internals
• Extension of model hydration
• Query builder augmentation
• Version tracking at ORM level
• Optional prevention of direct mutation via save()

A core implementation ensures:

• Convention over configuration
• Consistent developer experience
• Performance optimizations not possible externally
• Long-term maintainability

---

Backward Compatibility

• Feature would be opt-in.
• Only models extending AggregateRoot would use event sourcing.
• No breaking changes to existing applications.

---

Alternatives Considered

1. Do nothing

Developers can use external packages.

2. Create a community package

Possible, but limited in deep ORM integration.

3. Add versioning only (without full event sourcing)

Simpler, but significantly less powerful.

---

Questions for the Community

• Would first-class event sourcing support be valuable in your projects?
• Should projection support be included initially, or added later?
• Should temporal querying be limited to aggregate models only?
• Would you prefer this as a separate optional Laravel component?

---

Contribution Plan

If there is interest, I would be happy to:

• Implement the initial core abstraction
• Provide full test coverage
• Benchmark performance impact
• Prepare complete documentation
• Submit a pull request ready for review and experimentation

I’m fully committed to building and maintaining this as a long-term contribution to Laravel.

Looking forward to your feedback.

[shaedrich]

This would be a huge undertaking, so I doubt, Taylor would be willing to take such a step. Luckily, there's a great package called owen-it/laravel-auditing

[eslam-reda-div]

Thanks for the feedback — I completely agree that this would be a large undertaking, and that’s exactly why I’m proposing it as an opt-in, core-level feature, not a simple package.

Packages like owen-it/laravel-auditing are excellent for audit logs, but they solve a different problem. Auditing helps you see what changed, while this proposal focuses on making historical model state queryable and reconstructable.

With auditing, you can inspect old values, but you can’t do things like:

User::at('2024-03-01')->where('status', 'active')->get();

or load relationships as they existed at that point in time, or replay model state for debugging and recovery purposes.

The goal here isn’t to replace auditing packages, but to introduce a native temporal model capability — similar in spirit to system-versioned tables in some databases — while keeping it fully opt-in and backward compatible.

I totally understand the concern around scope, which is why I’m happy to start with a minimal, experimental implementation and iterate based on community feedback.