Filament Presence Laravel Package

Getting Started

• Install the package with Composer:

  composer require happenv-com/filament-presence
  

• Publish and run any package migrations/config if the package ships them:

  php artisan vendor:publish --tag="filament-presence-config"
  php artisan migrate
  

  Check the package README for the exact publish tags; not every Filament plugin needs both.
• Register the plugin on the Filament panel you want presence indicators in, usually in app/Providers/Filament/AdminPanelProvider.php:

  use Happenv\FilamentPresence\FilamentPresencePlugin;
  
  public function panel(Panel $panel): Panel
  {
      return $panel
          ->plugin(FilamentPresencePlugin::make());
  }
  

• If the package requires a trait or contract on your authenticatable model, add it to App\Models\User as documented. Then clear caches:

  php artisan optimize:clear
  

• First use case: show an online/offline indicator for users in a Filament resource or panel UI, then open two browser sessions with different users and confirm the indicator updates. As of v1.2.0, use hideWhen() to suppress the indicator for sessions where presence should not be shown, such as impersonated sessions or demo accounts.

Where to look first:

1. The package README for the exact plugin class, trait, and component names.
2. config/filament-presence.php if published.
3. The package src/ directory for the plugin class and Livewire/table components.
4. Your panel provider and User model for integration points.

Implementation Patterns

• Register presence per panel rather than globally. This keeps admin, tenant, and customer panels isolated and avoids showing the wrong guard’s sessions.
• Attach presence to the places where operators actually need it:
  • User resource tables: show who is currently online.
  • User infolists or profile pages: show current session/presence detail.
  • Dashboard widgets: show active users or sessions at a glance.
• Use hideWhen() for session-level suppression in v1.2.0:

  ->hideWhen(fn ($session) => $session->isImpersonated())
  

  Good candidates are impersonation sessions, shared demo accounts, service accounts, and sessions belonging to a different tenant or guard.
• Keep hideWhen() closures cheap. Prefer already-loaded model attributes or simple auth/tenant checks over per-row database queries.
• Pair hideWhen() with policy/visibility checks. Hiding an indicator is a UI concern; it is not an authorization boundary.
• For multi-guard or multi-tenant apps, verify that the panel’s auth guard matches the sessions the package reads. If the package exposes guard/session configuration, set it explicitly per panel.
• If the package polls for updates, tune the polling interval to your traffic. Presence is usually “near real time”, not audit-log accuracy.
• Test the integration with Livewire/Filament tests:

  livewire(ListUsers::class)
      ->assertSee('Online');
  

  For hidden cases, assert that the indicator text/component is absent when hideWhen() returns true.
• When upgrading to v1.2.0, update dependencies and re-run your panel/resource tests. The release adds hideWhen() and only bumps a CI dependency, so the main risk is integration behavior, not a known breaking change.

Gotchas and Tips

• Presence data is ephemeral. Do not treat it as an audit trail, login history, or security log.
• In multi-server deployments, session/cache storage must be shared and reliable. Redis or a shared database cache is safer than local file cache.
• hideWhen() hides the indicator, but it does not necessarily stop the underlying session from being tracked. Do not rely on it for privacy or access control.
• Watch out for auth-guard mismatches. A panel using web may show different sessions than a panel using an admin guard.
• Avoid expensive closures in hideWhen(). If the callback runs for every session row, eager-load relationships and avoid repeated queries.
• Clear config and view caches after changing panel registration, plugin config, or model traits.
• Filament plugins are panel-scoped. Registering the plugin in the wrong panel provider is a common reason indicators “don’t appear”.
• If presence appears stale, check the polling/refresh configuration and the cache/session driver before assuming the package is broken.
• The TruffleHog bump in v1.2.0 is CI-only and does not affect runtime behavior.
• Treat v1.2.0 as a low-risk feature release, but explicitly test the new hideWhen() behavior for impersonation, tenant scoping, and any custom session filters you rely on.