...
``` Define the `viewSessionReplay` gate in `SessionReplayServiceProvider` (or `AuthServiceProvider`) to control who can access the recording UI: ```php Gate::define('viewSessionReplay', fn (User $user) => $user->isAdmin()); ``` Schedule the prune command to clean up old recordings: ```php // routes/console.php or Kernel.php $schedule->command('session-replay:prune')->daily(); ``` That's it. Visit your app, then head to `/session-replay` (or the Filament panel if you installed the plugin) to see recordings. ## Two Recording Modes The package supports two fundamentally different strategies: | Mode | Behavior | Best For | |------|----------|----------| | `session` (default) | Records continuously from page load | Full-session auditing, UX research, onboarding flows | | `on_error` | Buffers the last *N* seconds in browser memory; uploads only when triggered | Production error debugging, minimal storage, privacy-sensitive apps | In `on_error` mode, the recorder keeps a rolling buffer (default 60 seconds, configurable 5–600 seconds, max 50 MB). When a trigger fires — JavaScript error, failed fetch/Livewire request, server exception (5xx), console.error, rage click, or a custom event — the buffer flushes to your server. You can also require user consent before upload: ```php // config/session-replay.php 'mode' => 'on_error', 'on_error' => [ 'buffer_seconds' => 60, 'max_buffer_mb' => 5, 'triggers' => ['error', 'request', 'console_error', 'rage_click'], 'ask' => true, // prompt before sending 'ask_again' => 3600, // re-prompt after 1 hour 'keep_pending' => true, // retry failed uploads from IndexedDB ], ``` This approach dramatically reduces storage and bandwidth while still capturing the moments that matter. ## Privacy by Default Session replay can easily become a privacy nightmare. The package bakes in sensible defaults: - **All inputs masked** — `mask_all_inputs: true` replaces values with `••••`. Password fields are *always* masked regardless of this setting. - **No IP storage** — the recorder never sends the client IP. - **Guests excluded** — `record_guests: false` by default. - **Livewire snapshots excluded** — internal Livewire payloads aren't recorded unless you opt in. - **Query parameter redaction** — a built-in list scrubs tokens, passwords, keys, emails, and other secrets from recorded URLs. You can fine-tune per element with data attributes: ```blade{{ $user->name }}
...
```
For stricter layouts, enable `mask_all_text: true` to record only structure — useful for compliance-heavy environments.
## Timeline Markers: Finding the Signal
Raw recordings are verbose. The package inserts **markers** at key moments so you can jump straight to the relevant section:
| Marker Type | Trigger |
|-------------|---------|
| `js_error` | Uncaught JavaScript exception |
| `failed_request` | Failed fetch/XHR or Livewire request (non-2xx) |
| `server_exception` | Laravel reports a 5xx via `Context::add()` |
| `web_vital` | LCP, INP, CLS thresholds crossed |
| `rage_click` | Rapid clicks on same element (frustration signal) |
| `page_view` | Navigation or SPA route change |
| `custom` | Your own `SessionReplay.marker('checkout_start', { orderId: 123 })` |
Markers appear as colored dots on the playback timeline. Filter by type, search by label, or click to jump — no scrubbing through 20 minutes of idle time.
## Linking Recordings to Your Logs
One of the most powerful integrations is automatic Context enrichment. When an exception lands in your log stack (Laravel Log, Flare, Sentry, Bugsnag, custom), the package adds two keys to Laravel's `Context`:
```php
// Automatically added when a recording exists for the current session
Context::add('session_replay', $recordingId); // UUID of the recording
Context::add('session_replay_url', $playerUrl); // Direct link to the player
```
Your error alert (Slack, email, PagerDuty) now includes a "Watch replay" link. Click it, and you're at the exact moment the error occurred — no guessing, no correlating timestamps across systems.
```php
// Manually tag a recording from your code
SessionReplay::tag('checkout_failed', ['order_id' => $order->id, 'error' => $e->getMessage()]);
```
## Database Schema and Storage
Six tables power the index (migrations are included):
| Table | Purpose |
|-------|---------|
| `replay_sessions` | One row per recording: user/tenant, URL, UA, device, viewport, counters (pages, events, chunks, bytes, errors, rage clicks), web vitals, timestamps |
| `replay_chunks` | Uploaded batches: sequence, file path, bytes, event count, time range |
| `replay_markers` | Filterable markers: type, label, payload, timestamp |
| `replay_assets` | Shared stylesheets/snapshots (deduplicated via hash) |
| `replay_asset_owners` | Workspace ownership for multi-tenant asset isolation |
| `replay_session_assets` | Links recordings to their assets |
Foreign keys cascade: deleting a `ReplaySession` removes chunks, markers, snapshots, and the physical files on disk. User and tenant IDs are stored as strings, supporting integers, UUIDs, and ULIDs. The unique index on `(session_id, seq)` in `replay_chunks` makes retries idempotent — safe for flaky networks.
Recorded events are stored as gzipped JSON chunks on any filesystem you configure (`local`, `s3`, `r2`, `ftp`, etc.). A 10-minute session typically compresses to 200–800 KB.
## Multi-Tenancy and Filament
If your app uses a `tenant_id` or similar scoping column, the package respects it automatically — recordings are scoped to the current tenant. A central database connection is supported for shared infrastructure.
For Filament v5 panels, a first-party plugin adds a resource to browse, filter, and play recordings without leaving your admin panel:
```bash
composer require packstub/filament-session-replay
```
## When to Reach for This
**Use it when:**
- You debug production errors and need visual context beyond stack traces
- You want session replay without sending user data to a third party
- You need to correlate frontend behavior (rage clicks, web vitals) with backend errors
- Your compliance requirements forbid external analytics scripts
- You already self-host infrastructure and want to keep it that way
**Consider alternatives when:**
- You need heatmaps, funnels, or product analytics — this is a replay tool, not an analytics platform
- Your team lacks ops capacity to manage storage growth (schedule `prune` aggressively)
- You need mobile app replay (rrweb is browser-only)
## Gotchas
- **CSP headers** — the inline recorder script needs `script-src 'self' 'unsafe-inline'` or a nonce. The package documents the exact hashes for `script-src` if you prefer strict CSP.
- **Large file uploads** — chunked uploads handle this, but ensure `client_max_body_size` (nginx) or `LimitRequestBody` (Apache) allows your chunk size (default 2 MB).
- **Queue the uploads** — the package uses a queued job for chunk persistence. Make sure your queue worker runs.
- **Storage costs** — even compressed, high-traffic sites accumulate gigabytes. Set `retention_days` in config and run `prune` daily.
- **Livewire polling** — frequent polls create noise. The package filters Livewire heartbeat requests by default, but check your marker list if it feels cluttered.
## Closing Thought
Session replay used to be a "nice to have" reserved for teams with budget for SaaS. packstub/session-replay brings it into reach for any Laravel team willing to run a few migrations and schedule a prune job. The privacy-first defaults, `on_error` mode, and Context integration make it practical for production — not just a staging toy. If you've ever stared at an exception trace wishing you could see what the user actually did, this package is worth an afternoon to set up.
## Sources
- Laravel News announcement: