Filament Connection Badge Laravel Package

Technical Evaluation

Architecture fit. The package is a pure presentation-layer addition to a Filament panel: one Alpine component registered through a PanelsRenderHook, one stateless JSON route, and CSS built on Filament's design tokens. It has no domain coupling, no persistence, no queue or scheduler usage, and nothing in the app depends on it. That makes it a leaf dependency — trivially removable if it disappoints — which is exactly the profile a TPM should prefer for a UX nice-to-have.

The one thing that makes it more than cosmetic is the design intent: the heartbeat hits a Laravel route rather than a static file, so a green badge is evidence that PHP, the router, and the middleware stack are alive. If someone "optimizes" this to ping_url=/favicon.ico, the feature degrades to a browser-online indicator and the business rationale disappears. That decision should be recorded, not left to whoever touches the config first.

Integration feasibility. Half a day including verification, not a sprint. composer require plus php artisan filament:assets (which is mandatory despite the "drop-in" framing — skipping it yields a dead, unstyled span, and it must be re-run after every composer update). Then a config publish, a Gate definition, and a smoke test in CI that asserts the heartbeat route returns {ok: true}.

Technical risk.

The counterweight to the low star count is genuine engineering discipline for a package this size: PHPStan level 6 with Larastan, Pest coverage of config defaults and route behavior, Pint + CI, pinned GitHub Actions, a SECURITY.md that openly describes the endpoint's threat surface, and Dependabot configured. That is a better maturity signal than the 0.06 composite score suggests.

Key questions to settle before approval.

1. Which panels get the badge — internal admin only, or tenant/customer-facing too?
2. Who is the audience, and what should they do when it turns red? An indicator with no defined response is a support liability.
3. Does the overlay ever block a critical in-flight action (approval, checkout, long form)? If so, disable show_overlay and ship the badge only.
4. Is there an existing health/status indicator we should consolidate with rather than run two?
5. What is our stated SLO, and does the badge's threshold config (full ≤200ms, medium ≤600ms) match it?
6. Who owns the fork if upstream goes quiet?

Integration Approach

Stack fit. Requires PHP 8.2+ (8.2/8.3/8.4), Laravel 10–13, Filament 4 or 5. It ships prebuilt assets through FilamentAsset with no Vite or npm step, so it slots into a Filament panel without touching the frontend build pipeline — meaningful for teams that keep their admin panel asset story deliberately boring.

Migration path. There is no migration; this is additive. The only real sequencing decision is whether you are replacing an existing topbar widget (a custom health dot, a queue-status indicator). If so, run the two in parallel for a release, compare signal quality, then retire the old one. Do not cut over blind — you will not know whether a red badge is the new package being wrong or the old one having been right.

Compatibility checks to run in staging, in this order.

• Filament version constraint actually resolved matches what you run in production (the "single code path for v4 and v5" claim is the one most worth verifying on a pinned older v4).
• WAF / reverse proxy / load balancer does not 403 or rate-limit the /_filament-connection-badge/ping prefix.
• CSP permits the inline Alpine component.
• If the UI is localized: en, ar, and ckb ship in-box; anything else needs a published translation file.

Sequencing.

1. Install in staging with FILAMENT_CONNECTION_BADGE_ENABLED=false as a kill switch already wired.
2. Publish config; harden in one block — route.middleware with Filament\Http\Middleware\Authenticate, a permission Gate ability, and route.throttle set to something like 120,1.
3. Add the heartbeat smoke test to CI.
4. Pilot on the internal admin panel for one to two weeks; watch for false-offline reports.
5. Expand to additional panels only after the pilot produces zero spurious overlay incidents.

Audience scoping. enabled is a single global boolean and cannot vary per panel — the per-panel, per-role lever is permission, evaluated at render time via auth()->user()->can(). Internal admin panel: no Gate, everyone sees it. Customer-facing panel: Gate it to support/super-admin roles only, or leave it off entirely and avoid explaining a red dot to end users who cannot act on it.

Operational Impact

Maintenance. Low ongoing cost, but not zero. Pin the version, treat php artisan filament:assets as part of every deploy that touches Composer, and assign one named owner to track upstream releases. The changelog is present and the 1.0.1 release shows active security hygiene (pinned action SHAs, Dependabot cooldown, a disclosure process) — a good sign, but a one-person project is still a one-person project.

Support. The badge is advisory and must be documented as advisory. The failure mode that generates tickets is not the badge being wrong — it is users interpreting "offline" as "my work was lost" or "the system is down for everyone." Ship a one-line policy with the release: the badge reflects your browser's ability to reach the app, nothing more; save your work and retry. Localization beyond the three shipped languages is a small, publishable follow-up.

Scaling. Cost scales as users × panels × (1 / ping_interval). The route is stateless with Cache-Control: no-store and does no I/O, so per-request cost is small — but it is additive and constant, and it lands on the same PHP workers that serve real work. For panels above roughly a few hundred concurrent users, raise ping_interval to 15–30s, keep route.throttle on, and confirm your APM can separate heartbeat traffic from business traffic so capacity conversations are not muddied.

Failure modes to pre-write runbook entries for.

Ramp-up. Negligible for developers — the README is unusually complete and the config surface is small and well-named. The real ramp-up is organizational: socializing what the badge means, who it is for, and what a user should do when it goes red. That is a TPM deliverable, not a documentation task.

TPM recommendation. Approve for internal admin panels only, as a scoped pilot with the route hardened and the overlay evaluated separately from the badge. It is a low-cost, low-lock-in UX improvement with a single genuinely valuable capability — proving the Laravel app is reachable rather than just the web server. Do not extend it to customer-facing surfaces until the pilot shows zero false-offline incidents and someone has committed to owning the fork if upstream stops.