Filament Activity Log Laravel Package

Technical Evaluation

Architecture fit. This package is a presentation layer only. It does not introduce a new persistence model or event pipeline — it renders Filament pages/components over the activity_log table that spatie/laravel-activitylog already owns. That separation is the single most important architectural fact for us: the risk surface we are adopting is UI + Filament coupling, not a new source of truth. Capture semantics (which models, which events, which attributes, batching) remain governed by Spatie's package and our own LogsActivity trait configuration, so we are not locked into this vendor for the data even if we drop the viewer.

Integration feasibility. High, and cheap to validate. The work is: composer require, register the plugin in the target PanelProvider, optionally publish the config, ensure the Spatie migration has run, and add the model trait where we want coverage. The plugin also ships a reusable component for resource view pages, plus a dedicated list page and (v3.1.0) a ListActivitiesByCauser page. There is no schema migration, no backfill, and no data transformation. A TPM should be able to timebox a spike to 2–4 engineering days including one audited model end-to-end.

Technical risk.

• Version-matrix coupling is the primary risk. Compatibility is tracked at the major level: Filament v4 support landed in v2.0.0, Filament v5 in v2.1.0, and Spatie laravel-activitylog v5 in v3.0.0. Our three constraints (Filament major, Spatie major, this package's major) must move together. Budget for this as a recurring upgrade tax, not a one-time install.
• Bus factor. The repository is effectively single-maintainer with community PRs; the changelog is dominated by translation additions and small fixes. Metadata shows 0 dependents, which means we would be among the earliest production adopters rather than following a well-worn path. Stars (233) indicate awareness, not deployment depth.
• Restore is a product decision disguised as a feature. v1.1.0 deliberately extracted restore authorization into a policy hook because "can view audit history" and "can rewind a record" are different permissions. Defaulting restore on would be a governance failure; we must treat it as opt-in per panel.
• Data-exposure risk. The viewer surfaces old/new JSON properties verbatim. If we log models containing PII, secrets, or payment identifiers, we have built an admin-accessible leak surface. Attribute allow/deny lists belong in the Spatie config, reviewed before the UI is enabled.
• Multi-tenancy is not solved by this package. If we run tenant-scoped panels, filtering the activity list to the current tenant requires scoping work in our own resource/page override. Assume custom code here.

Key questions to resolve before commit.

1. Which Filament major and which spatie/laravel-activitylog major are we on, and does that map cleanly to this package's v2.x vs v3.x line?
2. Which models/events are in scope for phase one (role and permission changes, deletions, payment state, exports, impersonation)?
3. Who may view the log, and is restore exposed to anyone at all?
4. What is our retention window for activity_log, and who owns the archival job?
5. Do we already run Spatie's package, or does this adoption also introduce the logging substrate?
6. Do we have a morph map, and is it stable enough that historical subject_type values will keep resolving after refactors?

Integration Approach

Stack fit. This is a native fit for Laravel + Filament panels on MySQL/Postgres. It assumes spatie/laravel-activitylog is installed and migrated, and it assumes the audited models use LogsActivity. If the team already has Spatie logging in place for compliance reasons, this package slots in with zero data-layer change — the integration is a panel registration and a permission gate. If not, we are making two adoptions at once and should sequence them separately so we can distinguish "logging is wrong" from "viewer is wrong."

Migration path. There is effectively no migration: adoption is additive and rollback is uninstalling the plugin and removing the panel registration, leaving the log data intact for a later viewer. The one-way door is capture: once we log a model, historical rows are permanent, and the shape of properties (old/new/attributes) is fixed at write time. Treat the first week of capture configuration as the design decision that actually matters, and treat the viewer as reversible.

Compatibility. Pin constraints explicitly rather than floating. The matrix to verify in CI or a staging panel: Filament major ↔ plugin major (v2.x for Filament v4, v2.1.0+ for Filament v5) and Spatie major ↔ plugin major (v3.x for laravel-activitylog v5). Run the panel in staging against a restored production-sized activity_log table — the list page's filtering and eager-loading behavior at 10M+ rows is the thing that will surprise us, not the install. Note the v1.0.5 fix for causer eager loading and v2.1.1's pagination trait cleanup; these indicate the table rendering path has had real bugs and deserves a load test rather than a smoke test.

Sequencing.

1. Enable Spatie capture first, narrowly: three to five high-value models, event allow-list, attribute deny-list for PII, batch_uuid on for bulk operations.
2. Install the viewer in a non-production or restricted panel, restricted to a single super-admin role via policy, to validate rendering against real data volume and real diff shapes (booleans, relations, arrays — all of which have had rendering fixes historically: v1.1.5 relational attributes, v1.1.10 booleans, v0.1.3 array values).
3. Add the reusable component to the highest-traffic resource view pages (the "what changed on this record" case), before the global list page.
4. Roll out the global Activity Log page plus ListActivitiesByCauser to support and trust-and-safety, with documentation and a saved-filter cheat sheet.
5. Enable restore last, if at all, behind a distinct policy ability and a per-panel config flag, with a written rollback protocol (restore is a write; it must be logged and reversible).

Operational Impact

Maintenance. Low code surface, non-trivial upgrade cadence. Releases are frequent but mostly small — translation additions, RTL and dark-mode fixes, single-line bug fixes. The releases that matter to us are the majors tied to Filament and Spatie (v2.0.0, v2.1.0, v3.0.0). Plan for one scheduled upgrade per Filament/Spatie major, owned by whoever owns the admin panel, with a staging verification pass. Do not treat this as a "set and forget" dependency; treat it as a UI dependency with the same upgrade discipline as the panel itself.

Support. This is the package's clearest operational payoff. "Who changed or deleted this record, and what did it look like before?" is a repeating ticket class that currently escalates to engineering. A filterable view by causer, subject, event, and date — plus the by-causer page for impersonation and offboarding investigations — converts that into a support-desk self-serve task. Budget a short enablement session and a one-page runbook for the support team; the value is only realized if they know the page exists and how to filter it.

Scaling. The bottleneck is the activity_log table, not the plugin. Two things follow: (a) ensure indexes on subject_type/subject_id, causer_type/causer_id, event, and created_at — the viewer's filters will do full scans otherwise, and this is the most likely production incident; (b) define a retention and archival policy with an owning job before volume accumulates, because deleting audit history later is a compliance conversation, not a maintenance task. The old/new JSON payloads are also the largest columns per row and the most likely to produce slow renders on attribute-heavy models; consider excluding large text fields from logging.

Failure modes to design against.

• Missing or un-migrated activity_log table — the panel page 500s on load. Add a deploy check.
• Morph alias drift — renaming a model class or changing the morph map orphans historical subject_type values; the viewer will show unresolved subjects. Lock the morph map before enabling capture.
• Deleted causers/subjects — the log outlives the user. Decide whether the viewer should show a tombstone label or fail gracefully; support staff will hit this on day one of offboarding reviews.
• Restore conflicts — rewinding a record can violate unique constraints or resurrect a row whose relations are gone. Restore must be gated, logged, and tested against the actual models in scope, not just the demo model.
• Permission gaps — the log is a high-signal target; a single misconfigured policy exposes cross-tenant or PII data to every panel admin. Gate by policy, verify with an impersonated low-privilege account, and re-verify on every major upgrade.
• Unbounded diffs — a bulk import or large JSON attribute change can produce a row that renders megabytes in the detail view.

Ramp-up. Engineering: half a day to install and one to configure capture correctly; the real effort is the attribute/event scoping review, which is a cross-functional decision, not a coding task. Support/ops: an hour of training plus a runbook. Total time-to-value is measured in days, and the ongoing cost is the major-version upgrade tax plus retention ownership — both of which should be explicitly assigned before adoption rather than discovered afterward.