rawand201/filament-connection-badge
Drop-in connection status badge for Filament panels. Shows live signal bars in the topbar, ping graph on hover, and optional full-screen offline overlay. Works with Filament v4/v5, matches theme/dark mode, supports RTL and translations.
## Product Decisions This Supports
- **Enhancing Observability for Filament Users**:
- **Proactive issue detection**: Surface real-time network latency/packet loss before users encounter performance degradation, reducing support overhead and improving admin panel reliability.
- **Developer experience (DX)**: Provide immediate feedback on backend health (e.g., slow APIs, regional latency) without requiring manual checks or logs. Aligns with SRE principles of "you build it, you run it."
- **Roadmap Prioritization**:
- **Low-effort, high-impact feature**: Justify inclusion in a "polish" or "observability" sprint with minimal dev time (~1 hour to install/configure) and tangible ROI (e.g., reduced "app is slow" tickets).
- **Phased rollout strategy**:
- **Phase 1**: Enable for internal Filament panels (dev/staging/prod) to monitor Laravel backend health.
- **Phase 2**: Extend to customer-facing dashboards (if using Filament for B2B portals) to build trust via transparency.
- **Phase 3**: Customize thresholds/overlays for specific use cases (e.g., high-latency regions).
- **Build vs. Buy Decision**:
- **Buy**: Avoid reinventing a niche UX component. This package handles edge cases (RTL, dark mode, i18n) and integrates seamlessly with Filament’s ecosystem. Custom dev would cost **2–4 dev days** (Alpine.js + Laravel route + CSS).
- **Leverage existing investments**: Works with Filament v4/v5, Laravel 10+/11+/12+/13+, and PHP 8.2+. No additional tooling (e.g., Vite) required.
- **Use Cases**:
- **Internal tools**: Monitor Laravel backend health for dev/ops teams using Filament panels (e.g., detect slow database queries or third-party API calls).
- **Customer-facing dashboards**: Reassure users of B2B SaaS products by visualizing system status (e.g., "Your data is syncing—here’s the latency").
- **Multi-region deployments**: Compare latency across AWS/GCP regions by configuring `ping_url` per Filament panel.
- **Legacy system integration**: Highlight performance bottlenecks (e.g., ERP connectors) with real-time feedback.
- **Security/Compliance**: Use the `permission` config to restrict visibility to authorized users (e.g., only admins see backend latency).
- **Data-Driven Decisions**:
- **Instrumentation**: Use the ping data to correlate latency spikes with specific actions (e.g., "High latency when users click ‘Export’").
- **Feature flagging**: Enable/disable via `FILAMENT_CONNECTION_BADGE_ENABLED` for A/B testing or gradual rollouts.
---
## When to Consider This Package
- **Adopt if**:
- Your team uses **Filament v4/v5** for admin panels, internal tools, or customer portals.
- You need **real-time connection feedback** (latency, packet loss, offline detection) without building a custom solution.
- Stakeholders prioritize **subtle but actionable UX signals** (e.g., "Why is this panel slow?").
- You’re already using **Laravel 10+/Filament** and want to avoid frontend build tools (no Vite/npm required).
- Your audience includes **technical users** (e.g., devs, ops, power admins) who can interpret latency metrics.
- You want to **reduce support overhead** by surfacing backend issues proactively.
- **Look elsewhere if**:
- You’re **not using Filament**: This is a Filament-specific package (no standalone Laravel or Livewire support).
- You need **server-side persistence**: This tracks pings client-side only (no database storage; use Laravel Horizon or similar for historical data).
- Your **audience lacks technical sophistication**: The tooltip’s sparkline + metrics may overwhelm non-technical users (consider a simpler "online/offline" badge instead).
- You require **granular control over ping logic**: The package uses fixed thresholds (e.g., `200ms` = full signal). For custom logic (e.g., dynamic thresholds), extend the Alpine component or build a bespoke solution.
- Your **environment blocks JavaScript**: The badge relies on Alpine.js for interactivity.
- You’re on **PHP <8.2** or **Laravel <10**: Hard dependency on modern Laravel/Filament.
- You need **multi-panel aggregation**: This tracks connection status per-panel; for cross-panel dashboards, integrate with a monitoring tool (e.g., Datadog, New Relic).
---
## How to Pitch It (Stakeholders)
### **For Executives (Business-Focused)**
*"This is a **5-minute install** that adds a ‘network health meter’ to our Filament admin panels—like a WiFi signal bar but for our backend. It **proactively surfaces latency issues** (e.g., slow APIs, regional outages) before users complain, reducing support overhead by **[X]%**.
- **For internal tools**: Our dev/ops teams will spot backend slowdowns instantly, cutting debugging time.
- **For customer portals**: Transparency builds trust—users see ‘Your data is syncing’ with real-time status.
- **No dev resources needed**: It’s a drop-in package with zero build steps, so we can roll it out today.
**ROI Hook**:
- *‘For every hour we save debugging “app not responding” tickets, this pays for itself.’*
- *‘If we enable this for [X] customer portals, it could reduce churn by [Y]% by making system status visible.’*
- *‘This is a **$0 cost** feature that aligns with our SRE goals of observability.’*
---
### **For Engineering (Technical Deep Dive)**
**Problem**:
Filament panels lack built-in observability for backend health (e.g., Laravel latency, API dependencies). Users experience slowdowns without context.
**Solution**:
The `filament-connection-badge` package adds:
1. **Topbar signal badge** (full/medium/low/offline) using Filament’s design tokens (automatic dark mode/RTL support).
2. **Real-time ping monitoring**:
- Laravel endpoint (`/_filament-connection-badge/ping`) measures round-trip time to prove the **app (not just static files)** is responsive.
- Configurable thresholds (e.g., `200ms` = full signal, `600ms` = warning).
3. **Interactive tooltip**:
- Sparkline of recent pings (rolling buffer of `max_samples`).
- Metrics: average latency, last ping, packet loss %, host.
4. **Offline overlay**: Full-screen alert when connection drops (auto-dismisses on recovery).
5. **Security**:
- Route can be locked to authenticated users (`middleware: ['web', 'auth']`).
- Optional `permission` gate (e.g., `viewConnectionBadge`) for fine-grained access.
**Why This Over Custom Dev?**
| Criteria | Package | Custom Build |
|-------------------------|-----------------------------------|----------------------------------|
| **Dev Time** | 1 hour (install + config) | 2–4 days (Alpine.js + Laravel) |
| **Edge Cases** | RTL, dark mode, i18n (built-in) | Manual implementation |
| **Maintenance** | MIT-licensed, community updates | Your team’s burden |
| **Filament Integration**| Native (v4/v5, hooks, assets) | Risk of breaking updates |
| **No Build Step** | Zero Vite/npm dependency | Requires frontend tooling |
**Implementation Steps**:
1. **Install**:
```bash
composer require rawand201/filament-connection-badge
php artisan filament:assets
ping_url to target specific endpoints (e.g., /api/health).thresholds for your SLA (e.g., full: 100, medium: 300).permission for role-based visibility.vendor:publish.Data Opportunities:
Risks/Mitigations:
60,1 = 1 request/minute). Disable with FILAMENT_CONNECTION_BADGE_THROTTLE=null.navigator.onLine + ping confirmation. Adjust ping_interval (default: 5s) for noisy networks.resources/js/filament-connection-badge.js) for advanced logic.Alternatives Considered:
How can I help you explore Laravel packages today?