Filament Connection Badge Laravel Package

Product Decisions This Supports

• Support-cost reduction for "the app is down" tickets. The badge distinguishes browser offline from server not responding, which is the ambiguity behind most "it's broken / it's slow" reports from ops, warehouse, and field users. The tooltip's average ping, last ping, and packet-loss figures turn a vague complaint into a screenshot.
• Build vs. buy for a "connection quality" UI. The alternative is a sprint of frontend work (Alpine component, polling, sparkline, overlay, RTL-safe layout, theme tokens). That is roughly 3–5 days of a Filament-literate engineer plus permanent maintenance. At MIT license and zero cost, this is a clear buy — provided the risk profile is acceptable.
• Roadmap input for latency-sensitive features. Before committing to a "live dashboard" or "realtime queue monitor" epic, ship this for a week and collect the data. If median ping to the admin panel is 400ms+, that changes the design of every realtime feature you build, and it belongs in the roadmap as infrastructure work.
• Deployment and regional rollout decisions. If your users are on poor or intermittent links — MENA, South Asia, field/mobile, satellite — the online/offline ratio and ping distribution is real evidence for CDN investment, edge caching, or a lighter mobile-first panel. Arabic and Kurdish Sorani translations being first-party is a signal the author built this for exactly that audience.
• Scope decisions on per-role visibility. The permission config is a Gate ability evaluated at render time, so the badge can be surfaced to support/super-admin roles only and hidden from customers. That is a product lever, not just a security one — decide deliberately whether end users should see your infrastructure's health.
• Not a monitoring replacement. This is a client-side smoke signal, not observability. Do not let it displace real APM/uptime tooling on the roadmap; treat it as a UX affordance that shortens the path from complaint to diagnosis.

When to Consider This Package

Adopt when:

• You run Filament v4/v5 panels for internal users, ops staff, or a distributed/mobile workforce where "is it me or is it the app?" is a recurring support pattern.
• Your stack is already on the supported matrix: PHP 8.2+, Laravel 10–13. No version gymnastics required.
• You have an engineer who can spend half a day on the install and the hardening — the heartbeat route is publicly reachable under web middleware by default, so route.middleware => auth (or Filament's Authenticate), route.throttle, and the permission Gate belong in the same commit, not a follow-up ticket.
• You accept the operational footnote: assets ship pre-built and must be republished via php artisan filament:assets — including after every composer update. If that will silently break styling, add it to your deploy checklist first.

Look elsewhere (or vendor it) when:

• Single-maintainer dependency risk is unacceptable. Six stars, zero dependents, v1.0.x. That is not a knock on quality — the changelog shows PHPStan level 6, Pest tests, CI, pinned Actions, SECURITY.md, Dependabot — but it is a one-person project with no downstream users to catch regressions. If your policy requires a maintained-by-many dependency for production admin surfaces, either vendor the ~small surface area into your app or budget for a fork.
• You need SLA-backed support, a security response commitment, or vendor liability.
• Your panel is customer-facing and brand-critical; the visual surface is small and token-based, so a bespoke implementation may be preferable to an unfamiliar badge in your topbar.
• You need server-side persistence or historical connection analytics — this is explicitly stateless, in-browser, last-N-samples only. Nothing is stored, nothing is queryable.
• You are on Filament v3 or a non-Filament admin stack. Not applicable.

Risk note to weigh: the publicly reachable heartbeat is the one thing I would not ship without configuration. It is a low-severity surface (a JSON {ok:true} and a 403 path), but it is an unauthenticated route into your PHP stack that an attacker can poll. Throttling and auth middleware are config, not defaults. That is fixable in ten minutes and should be treated as mandatory.

How to Pitch It (Stakeholders)

To executives: A small, free, MIT-licensed add-on for our admin panel that shows each user a live connection-quality indicator and a clear "you're offline" screen. The business case is support load: it kills the "the system is down" ticket that turns out to be someone's Wi-Fi, and it gives us real latency data from actual users before we invest in realtime features. Cost is one engineer for roughly half a day including security hardening. Risk is that it is a young, single-maintainer open-source package — mitigated by pinning the version and owning the fork if needed.

To engineering: Drop-in Filament v4/v5 topbar badge — an Alpine component polling a package-registered JSON heartbeat route through Laravel's router and middleware, so it measures your app, not nginx serving a static file. Rolling sparkline, avg/last ping, packet loss, offline overlay, theme-token colors, RTL-safe, en/ar/ckb translations. Zero build step; assets publish via filament:assets and must be republished on deploy. Quality signals are good for a v1: PHPStan level 6, Pest, CI, pinned Actions, SECURITY.md. Two things we do before it touches production: lock the heartbeat route behind auth middleware plus throttle, and gate the badge with a permission ability so it is scoped by role rather than globally on. Add a smoke test on the ping route to CI. Then pilot on the internal panel for a week and read the ping distribution — that number informs the realtime roadmap.