Skip to content

About

Session replay for Laravel, built on rrweb: a recorder with privacy defaults, token-signed ingest, recordings on your own disk and database, a player with errors, failed requests and rage clicks on the timeline, behind a gate you define. The engine behind Filament Session Replay; runs without Filament.

Topics

Resources

Contributing

Security policy

Stars

76 stars

Watchers

0 watching

Forks

Repository files navigation

Session Replay for Laravel

Session Replay for Laravel — watch what happened, inside your own Laravel app

Latest Version on Packagist Tests Total Downloads License Sponsor

Record what a person did in the browser, keep the recording on your own disk and database, and watch it inside your own app, behind a gate you define. Built on rrweb. Free and open source (MIT).

"The form did nothing when I clicked save" becomes a 40-second replay with the console error and the failed Livewire request marked on the timeline.

A replay in the built-in viewer: the pointer clicks "Pay" again and again, the payment fails, and the server error's details open with its report id and "Open in logs"

Features

  • One Blade directive: @sessionReplay before </body> records the page, with nothing to build or publish.
  • Private by default: every input masked, no IP address stored, an anonymous mode, sensitive pages left out.
  • Recordings stay with you: gzip chunks on any Laravel disk, the index in seven tables on your connection.
  • Markers on the timeline: errors, failed Livewire requests, web vitals, rage clicks, page views and your own moments.
  • Only when something goes wrong: keep the last minute in the browser and upload it on an error, after asking if you like.
  • Small recordings: stylesheets stored once, unused attributes dropped, batches gzipped in the browser.
  • A gate decides who watches: viewSessionReplay guards the list, the player and every file behind them.
  • A link in every log line: the recording's id and URL in Laravel's Context, so error reports point at the replay.
  • Multi-tenant aware: a recording stays in one workspace, and the tables can live on your central connection.
  • Friendly to cached pages: the recorder's token can outlive a full-page cache.
  • Five languages: the viewer and the player in English, German, Spanish, Romanian and Russian.

Quick start

composer require packstub/session-replay
php artisan session-replay:install

Put the recorder in the layouts you want recorded:

    @sessionReplay
</body>

Decide who may watch, in the app/Providers/SessionReplayServiceProvider.php the installer published:

use Illuminate\Support\Facades\Gate;
use Packstub\SessionReplay\Models\ReplaySession;

Gate::define('viewSessionReplay', function ($user, ?ReplaySession $session = null): bool {
    return $user->is_admin;
});

Schedule the clean-up in routes/console.php:

use Illuminate\Support\Facades\Schedule;

Schedule::command('session-replay:prune')->daily();

Sign in, click around, then open /session-replay.

How it works

  1. Recorder. @sessionReplay renders a small config object and a deferred script. The script records the DOM and what happens to it with rrweb, one recording per browser tab, continued across page loads until the tab sits idle.
  2. Signed token. When the page renders, the server signs who is signed in, the workspace, an impersonator and your own properties with the app key (signed, not encrypted: the page's source shows them). The recorder sends that token back with every upload, so the ingest endpoint needs no session, no cookie and no CSRF token.
  3. Ingest. Every few seconds the recorder uploads a gzip batch with a small index next to it (markers, counts, the stylesheets the batch references). The server stores the file and updates the index; it never parses the events.
  4. Storage. Chunks go to sessions/{id}/{seq}.json.gz on your disk, stylesheets to assets/ under the hash of their content, the index to replay_sessions, replay_chunks, replay_markers and replay_assets.
  5. Viewer. /session-replay lists recordings; the player loads the manifest, the chunks and the stylesheets through routes that check the viewSessionReplay gate for that recording on every request.

Privacy defaults

Default Setting
Every input masked, passwords always privacy.mask_all_inputs
Guests are not recorded guests
No IP address stored not configurable
Livewire component state (wire:snapshot) never enters a recording size.strip_attributes
Recordings deleted after 30 days retention.days
Nobody can watch outside local until the gate exists viewSessionReplay

See Privacy for masking, consent and wording for your privacy policy.

Documentation

Guide What it covers
Installation Requirements, the install command, the directive, the gate, the scheduler
Recording The directive and its options, who is recorded, sessions and sampling, markers, Livewire, CSP
Privacy What is recorded, masking and blocking, consent, retention, policy wording
Watching replays The gate, the built-in viewer, the player component, models and scopes
Storage Disk layout, tables, multi-tenant apps, sizes and limits, pruning
Error tracking The recording's id and URL in Laravel's Context
Assist Help requests: a visitor asks (SessionReplay.assist.request() or a "Get help" button), support claims it or offers help from the Live tab; with Holler for Laravel, a live stage in the viewer: the visitor's page mirrored as it happens, remote control, annotations, audio and screen share, each with the visitor's consent
Configuration Every key in config/session-replay.php

Assist's help-request queue works with this package alone. Its live view runs on Holler for Laravel (packstub/holler), and in a Filament panel also on Filament Holler; both are released separately, so see their READMEs for how to install them.

Guide: Session replay in Laravel and Filament, on your own server, a walkthrough from the first recording to watching it behind your own gate, with measured storage sizes.

In a Filament panel

packstub/filament-session-replay puts the sessions inside a Filament v5 panel: a filterable resource, the player with timeline tabs, a relation manager for your users, masking declared on the form field. It requires this package and records through it.

Alongside other tools

PostHog, Sentry, Microsoft Clarity and OpenReplay are great choices for product analytics, error monitoring and replay as a platform. This package is for replay inside your own app, next to your own models, on your own storage. They work well together.

Testing and development

composer test     # Pest
composer lint     # Pint
npm test          # the recorder's and the stage's pure functions
npm run build     # resources/js -> resources/dist
composer serve    # a page to record and the viewer, on :8000 (/agent signs in as support for Assist)
npm run test:e2e  # Assist end to end in two Chromium browsers (needs packstub/holler, see AGENTS.md)

More from Packstub

Other Packstub packages that sit well next to this one:

  • Filament Tenancy (paid): a database per tenant for Filament panels, built on stancl/tenancy. Session Replay keeps every recording in its workspace and its tables can stay on the central connection, so the two fit together.
  • Account Switcher for Laravel: impersonation, linked accounts and one-click developer logins, with every switch in an audit log.
  • Agents for Laravel: an AI agent and an MCP server from one list of tools, under your app's own authorization.
  • Filament Flow: visual workflow automations for a Filament panel, with triggers, conditions and actions drawn on a canvas.
  • Filament Kanban: a Kanban board for Filament with instant drag and drop and rules checked on the server.
  • Nitpick: themes for Filament panels, and a way for every person to pick their own.

All plugins: packstub.dev/plugins.

Packstub is made by XLITE, a small studio that also builds Laravel and Filament apps for clients.

Credits

  • rrweb (MIT) records and replays the DOM.
  • web-vitals (Apache-2.0) measures LCP, INP and CLS.

License

MIT. See LICENSE.md.

About

Session replay for Laravel, built on rrweb: a recorder with privacy defaults, token-signed ingest, recordings on your own disk and database, a player with errors, failed requests and rage clicks on the timeline, behind a gate you define. The engine behind Filament Session Replay; runs without Filament.

Topics

Resources

Contributing

Security policy

Stars

76 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages