Filament Activity Timeline Laravel Package

Product Decisions This Supports

• Audit trail vs. raw log dumps. The package reframes activity logging as a user-facing feature rather than a developer convenience. That unlocks a real product decision: do we ship an "Activity" tab in the admin panel that support and operations staff can read, or do we keep logs as a debugging artifact only engineers can interpret? This plugin makes the first option cheap.
• Build vs. buy on admin-panel UX. If you're already on Filament, the alternative is a custom infolist widget plus your own label/translation layer around spatie/laravel-activitylog. That's roughly 1–2 weeks of design, localization, and edge-case work (attribute casting, relation resolution, empty states). Adopting this narrows the build to configuration and copywriting.
• What staff are allowed to see in a timeline. The widget is mounted with a hidden_attributes list, and v1.0.2 hardens that boundary: a crafted request can no longer swap the widget's presentation overrides and reveal attributes it was mounted to hide. This is a product/privacy decision you now get to make explicitly — which fields (salary bands, internal notes, margin, PII) appear in change history — rather than one that leaks through UI state.
• Trustworthiness of the "no history" state. A denied or failed read no longer collapses silently into the same empty panel as a record with genuinely no activity; authorization failures now surface as a 403. That matters because an empty timeline that is actually a permissions bug is worse than an error — staff infer "nothing changed" and act on it.
• Localization roadmap. "Localized business events" implies per-locale event phrasing. That's a genuine product capability — a French ops team seeing Client : ACME France → Dupont Conseil in French, not English enum keys. It supports decisions about multi-market rollout and whether admin surfaces are localized at all.
• Support and CS workflow. A readable timeline on the customer/order record reduces "what changed and who changed it?" tickets. This is a measurable lever: track ticket deflection or time-to-answer on record-state questions before and after.
• Compliance and accountability features. Change history is a recurring requirement in B2B procurement, finance, and healthcare-adjacent sales cycles. This lets you scope an audit-history item into a release without treating it as a platform initiative.
• Performance guardrails as a product default. The new pagination.max_per_page ceiling (500 by default) bounds how much history one request can pull, which makes "activity tab on a high-volume record" a safe default rather than something that needs a bespoke performance review.
• Feature-level use cases it unlocks: order/quote revision history, CRM field-change narratives ("Owner reassigned"), subscription and billing state transitions, approval trail on multi-step workflows, and "last touched by" context on long-lived records.

When to Consider This Package

Adopt when most of the following hold:

• The product runs Filament v3/v4 and the audience for history is admins, ops, or support — not end customers via a public API.
• You already use, or are willing to adopt, spatie/laravel-activitylog as the underlying store; this is a presentation layer, not a logging engine.
• Localization matters across at least two locales, or you want human-readable labels instead of column names and IDs.
• The change surface is well-modelled — you can name your events and attributes. Semantic timelines degrade into the same noise as raw diffs if your data model is a generic JSON blob.
• You will pin at ^1.0.2 or later. Earlier 1.x versions let a crafted Livewire request rewrite the widget's public properties, including the presentation overrides that carry the hidden_attributes mount-time list. This is a one-line composer change and should not be a debate.
• You configure the widget through mount() or an extended timeline(), not through $wire.set(...) from your own JavaScript. If you do drive it from JS, v1.0.2 will throw CannotUpdateLockedPropertyException and you need a small refactor before upgrading.
• You can accept the maintenance burden of a small package: minimal adoption (9 stars, 0 dependents), a single maintainer. Budget for the possibility of forking.

Look elsewhere or build in-house when:

• You need history exposed to customers through an API or public portal — you'd be coupling your customer contract to a presentation plugin.
• Your audit requirements are regulatory-grade (tamper-evident, immutable, retained for years, exportable to auditors). A Filament view is not a compliance system; you need append-only storage, retention policy, and access logging underneath.
• You're not on Filament, or you're on a Livewire stack where a bespoke Blade partial is closer to the goal.
• You want analytics — aggregate change rates, funnel reconstruction, anomaly detection. This is a per-record viewer, not a reporting layer.
• Volume is high and you need retention/pruning, partitioning, or async writes; those are database and queue concerns this package doesn't address.
• You depend on large unbounded page sizes (a wall-mounted ops display, an export-by-scrolling view). The 500-row default ceiling is sane, but confirm your use case fits before assuming you can raise it.

Practical adoption stance: upgrade to at least 1.0.2, pilot on one internal admin resource behind a feature flag, and write a fallback plan (fork the renderer, keep the underlying log schema unchanged) so the exit cost stays low. Pin the version, treat major Filament upgrades as a scheduled compatibility check, and re-read release notes for security entries — this one is the second-order kind of fix a small package often never ships, so its presence is worth weighting.

How to Pitch It (Stakeholders)

To executives: "Our admin panel currently shows change history as a developer dump — status: 1 → 2, customer_id: 14 → 27. This package turns that into plain-language, localized entries staff can actually read: Status: Pending → Approved, Client: ACME France → Dupont Conseil. It's an MIT-licensed presentation layer over logging we already do, so the investment is days, not a sprint. The payoff is fewer 'what changed?' support tickets and a credible audit-history answer in B2B sales conversations. The version we'd adopt also closes a flaw where a tampered browser request could reveal fields the timeline was configured to hide — that's patched, and it's the reason we pin a minimum version rather than taking whatever is latest."

To engineering: "It's a Filament plugin that renders spatie/laravel-activitylog entries as semantic, translated events. We keep our existing logging schema; this only changes how the timeline is displayed and labelled. Ship ^1.0.2: it locks the widget's public properties, caps per_page at a configurable ceiling (500 default), and stops swallowing AuthorizationException into the empty state so denials return 403. No data migration. Two upgrade notes: stop driving the widget with $wire.set(...) — configure via mount() or an extended timeline() — and if we published the config, add pagination.max_per_page. It has CI, tests, and PHPStan, and the scope is deliberately narrow. The risk is still bus factor, not complexity — one maintainer, minimal adoption. Mitigation: pin the version, pilot on one resource, and be prepared to vendor the renderer if it goes stale."

Framing the caveat honestly: early-stage package, minimal adoption, so we're partly betting on it and partly buying a well-scoped reference implementation we could own ourselves. The security release cuts both ways: it's evidence the maintainer responds to real vulnerability reports, and it's a reminder that a small presentation package sitting on top of employee-visible PII is still attack surface. Both are acceptable for a UI-layer dependency with no data migration and no lock-in on the log store.