Filament Event Sourcing Laravel Package

Getting Started

This package plugs Filament panels into an event-sourced Laravel app, giving you UI for inspecting stored events (and typically replaying/rebuilding projections) without writing bespoke admin screens.

Minimal path:

1. composer require albertoarena/filament-event-sourcing — as of v1.2.0 the constraint accepts Filament 4 and 5, so it drops into an existing panel on either major without touching your code.
2. Register the plugin on your panel provider (->plugin(EventSourcingPlugin::make())) inside panel() in e.g. app/Providers/Filament/AdminPanelProvider.php.
3. Run php artisan filament:assets / clear caches (php artisan optimize:clear) so the new nav items and views show up.
4. Confirm your underlying event-sourcing package (typically spatie/laravel-event-sourcing) is installed and its stored_events table is migrated — this package reads from it rather than owning storage.

Where to look first:

• The panel navigation after registration — that's where the package's pages/resources surface. Open each one against a seeded/dev database before wiring anything into production.
• The package's config/ file (publish with php artisan vendor:publish --tag="filament-event-sourcing-config") — this is usually where table names, model bindings, and page/navigation toggles live.
• Its README section on panel registration; the Filament 5 support in 1.2.0 is constraint-only, so 4.x docs and examples apply unchanged.

Best first use case: point it at a single aggregate in a local or staging database and use it to eyeball the event stream for one aggregate UUID. That validates the whole chain (DB connection, model binding, authorization) with the least blast radius before you let anyone replay anything.

Implementation Patterns

Read-only inspector on shared panels. The lowest-risk pattern: register the plugin on an admin panel, gate it behind a policy/permission, and treat it purely as observability. Developers debug "why is this order in this state" by reading the stream instead of adding temporary dd() calls.

Replay behind a dedicated panel or gate. If you use the package's replay/rebuild actions, put them on a panel only ops/dev can reach, or wrap them behind a Gate/permission check. Replays are write operations against your read models — treat them with the same care as a queue restart, not like a Filament table refresh.

Pair it with seeders and factories for onboarding. New developers get the most value when a db:seed produces a handful of aggregates with realistic multi-event histories; the plugin then doubles as living documentation of your domain events. Keep a seeder that produces one long stream (10+ events) so pagination and ordering in the UI get exercised.

Use it as your event-versioning smoke test. After bumping an event class or changing an upcaster, open the affected aggregate in the UI and confirm old events still render. This catches serialization/EventSerializer breakage faster than reading test output.

Filament 4 → 5 migration workflow. Because v1.2.0 only widens the constraint, the upgrade path is: bump filament/filament to ^5.0 in your app, run composer update, then run your own test suite plus a manual pass over the plugin's pages (tables, filters, actions, modals). The package's CI covers both majors, but your panel's other plugins and custom pages are the real risk surface — do the Filament upgrade and the package bump in the same PR so regressions are attributable.

Keep it out of the request path. Nothing here should be called from application code. If you find yourself wanting programmatic access, use your event-sourcing package's repository/projector APIs directly rather than routing through Filament pages/resources.

Gotchas and Tips

• PHP 8.2 + Filament 5 is allowed but untested. The package's own constraint permits it; CI skips it because the test tooling won't install. If you're on PHP 8.2 and moving to Filament 5, you are the test suite — either bump to PHP 8.3+ for that combination or budget for manual verification of the plugin's pages.
• A widened constraint is not a code change. v1.2.0 has no API, config, or behaviour changes. If something behaves differently after upgrading, suspect the Filament major, your other panel plugins, or your own customizations — not this package. Pin Filament and bisect accordingly.
• composer update may not move you. If your lock file already resolved against 1.1.0, run composer update albertoarena/filament-event-sourcing --with-dependencies explicitly; a bare composer update on a large app can leave the plugin pinned while everything around it shifts.
• Cache and asset staleness after registering the plugin. Nav items, icons, and views are the usual casualties. php artisan optimize:clear && php artisan filament:assets before you start debugging registration logic.
• Authorization is your responsibility. Filament resources respect policies, but event data is often more sensitive than your normal models (payloads frequently contain PII, tokens, or full snapshots). Verify non-admin users can't reach the pages, and consider a dedicated gate rather than relying on the default panel access rules.
• Large streams and wide payloads. Event tables grow monotonically; an aggregate with thousands of events or fat JSON payloads will make the detail view slow and memory-hungry. Watch query counts on the list pages and avoid opening production aggregates with very long histories in a browser tab — check whether the package's config exposes pagination/per-page settings.
• Replay idempotency. If you use replay/rebuild actions, confirm your projectors are idempotent and that replays don't double-dispatch side effects (emails, webhooks, third-party calls). This is a property of your projectors, not the package, and it's the most common way these UIs cause incidents.
• Extension points. The practical ones are the published config (table/model bindings, navigation labels, page enable/disable) and Filament's own resource/page extension (overriding views, adding table actions via a custom page class). Before forking, check whether the page is registered conditionally through config — that's usually the supported seam.
• No 1.1.0 → 1.2.0 migration steps exist. No published migrations, no config republish required. If the package's docs suggest republishing config, diff it against yours rather than overwriting.