Download the PHP package albertoarena/filament-event-sourcing without Composer

Filament Event Sourcing

Integrate spatie/laravel-event-sourcing with Filament admin panels.

Filament assumes Eloquent CRUD. Event sourcing routes writes through aggregates and reads through projections. This package bridges the two without hiding either side. It lets Filament resource pages persist through your aggregates, gives you a read-only audit trail of stored events, and adds a config-gated page to replay projectors. You always write the aggregate call; the package provides the plumbing.

This package does not generate aggregates, events or projectors, and it does not map form state to domain commands. Those remain your decisions.

Event history at a glance

Add the HasStoredEvents trait to a projection model and you can drop a full, read-only event history onto any record, either as a relation manager or as a slide-over action:

The action lists the aggregate's events in order, with the version, timestamp and an expandable JSON payload for each event.

Requirements

• PHP ^8.2
• Laravel ^11.0 | ^12.0
• Filament ^4.0
• spatie/laravel-event-sourcing ^7.0

Installation

Register the plugin on your panel and opt in to the features you want:

Publish the config if you need to change the defaults:

Write bridge

The write bridge keeps Filament's full page lifecycle (form validation, mutate hooks, notifications and redirects) and replaces only the persistence step. You implement one method per operation; the package generates the uuid, resolves the resulting projection and reports errors.

The examples below use a Post aggregate with createPost, changeTitle and deletePost methods, recording PostCreated, PostTitleChanged and PostDeleted events, plus a synchronous PostProjector that maintains a Post projection model.

[!WARNING] Projectors must run synchronously for resources managed by Filament. The write bridge reads the projection back immediately after the aggregate persists, so a queued projector will not have created it yet and a ProjectionNotFoundException is thrown. Keep the projectors behind managed resources synchronous, or run the queue worker before the read.

Creating

The trait generates the uuid with Str::uuid(). Override newAggregateUuid() if you derive uuids differently.

Editing

Deleting

EventSourcedDeleteAction keeps the confirmation modal, notification and table refresh of Filament's DeleteAction, but never calls $record->delete() itself. Your projector owns the projection's lifecycle. Provide a ->using() closure that calls your aggregate:

If you forget the ->using() closure, the action throws a LogicException showing the snippet above.

Audit tooling

Stored Events browser

Enable storedEventsResource() on the plugin to add a read-only resource over Spatie's stored event model. It lists every stored event with its aggregate uuid, version, event class and timestamp, filters by event class, aggregate uuid and date range, and shows the full event payload as pretty-printed JSON. It never creates, edits or deletes events.

Per-record event history

Add the trait to your projection model:

The trait is primary-key agnostic. It links the aggregate uuid column (the aggregate_uuid_column config value, or a getAggregateUuidColumn() method on the model) to the stored events, so it works whether your projection uses a uuid primary key or an id primary key with a separate uuid column.

Then expose the history in either of two ways:

The history modal shows the latest 100 events with a notice when more exist.

Replay page

Enable replayPage() on the plugin to add a page that replays projectors one at a time. It is off by default and gated three ways: the plugin option, the replay.enabled config flag and an optional authorization ability. All three are checked again on the server before a replay runs.

[!WARNING] A replay runs synchronously inside the web request and can take a long time on large event stores. For production, prefer the CLI: php artisan event-sourcing:replay.

Replays must be safe to run. Spatie's replay does not wipe your read model: a full replay calls resetState() on each projector only if that method exists. Projectors behind Filament managed resources should be replay safe, either by implementing resetState() to clear their projection, or by making their handlers idempotent (for example with updateOrCreate). This package does not reset projections for you.

Adopting in an existing app

When you add this package to an app that already has data, new and existing records behave differently.

Records created through your aggregates after adoption are fully event sourced. Their events live in the stored events table, so they appear in the audit tooling and a projector replay rebuilds them.

Rows that already existed, created by ordinary Eloquent writes, have no events behind them. They keep working for reads, but they are not event sourced:

• Editing one through the write bridge produces an incomplete event stream, a change event with no preceding creation event.
• They are not replayable. A replay rebuilds the read model from the event store, so records with no events are not recreated, and a replay that resets the projection first will drop them.

To bring existing rows into the model, backfill one initial event per row, a one-off command you write that records their current state, so the event store becomes the source of truth. This package does not perform that CRUD to event sourcing migration for you; it is a domain decision that only you can make.

Configuration

Testing

Changelog

See CHANGELOG.md for recent changes.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md for reporting vulnerabilities.

Related packages

• albertoarena/laravel-event-sourcing-generator generates aggregates, events, projectors and reactors for bounded contexts.
• albertoarena/claude-laravel-event-sourcing is a Claude Code skill that helps design event-sourced domains and scaffold code.

License

The MIT License (MIT). See LICENSE.md.