Ehsan Bagherzadegan
Back to articles
7 min read

Self-Hosted Session Replay for Laravel with packstub/session-replay

A practical guide to packstub/session-replay — a self-hosted, privacy-first session replay package for Laravel that stores recordings on your infrastructure, links them to error logs via Context, and offers an error-only mode to minimize storage.

Debugging production issues often feels like detective work with missing evidence. Logs tell you *what* happened — an exception, a failed request, a timeout — but they rarely show *how* the user got there. Session replay fills that gap by recording the user's browser session as a video-like timeline you can scrub through: clicks, scrolls, form inputs, network requests, console errors, and Livewire interactions. Until recently, session replay meant sending data to a third-party SaaS (LogRocket, FullStory, Sentry Replay). That raises privacy concerns, adds cost, and creates vendor lock-in. **packstub/session-replay** changes the equation: it's a self-hosted, open-source (MIT) package that stores recordings on your own infrastructure — local disk, S3, R2, any Laravel filesystem — with the index in your database. No external dependencies, no data leaving your control. Released in early November 2026 (v1.1.0 on November 4), the package is built on [rrweb](https://github.com/rrweb-io/rrweb), the same open-source recorder powering many commercial tools. It integrates with Laravel through a single Blade directive, respects privacy by default, and links recordings to your logs via Laravel's Context system. ## Installation and First Recording ```bash composer require packstub/session-replay php artisan session-replay:install ``` The installer publishes a config file, runs migrations (six tables), and registers the `@sessionReplay` Blade directive. Add it to your main layout, right before ``: ```blade

...

``` 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: