Bug reports like “the checkout button did nothing” are hard to act on. Session Replay for Laravel, a new package from Packstub by Ion Căliman, lets you watch what the user did instead of guessing. It records the page with rrweb, stores the recordings on your own disk and database, and plays them back inside your app behind a gate you control. Laravel News covered it on 16 November 2026. This tutorial walks through installing it, keeping it private, recording only when something breaks, and linking replays to your logs.

What you get

  • One Blade directive turns on recording, with no front-end build step.
  • Timeline markers for JavaScript errors, failed Livewire and fetch requests, server exceptions, web vitals (LCP, INP, CLS) and rage clicks.
  • An error-only mode that keeps the last minute in the browser and uploads only when something fails.
  • Replay links added to your logs through Laravel’s Context.
  • Privacy defaults: every input is masked, guests are not recorded, and no IP address is stored.
  • Self-hosted storage as gzip chunks on any Laravel filesystem disk, indexed in your database.
  • An optional Filament v5 plugin.

Requirements: PHP 8.3 and Laravel 12 or 13.

Step 1: Install the package

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

The installer publishes the config and a SessionReplayServiceProvider, which is where you define who can watch recordings.

Step 2: Add the recorder to your layout

Put the directive just before the closing </body> tag in each layout you want to record:

    {{-- resources/views/layouts/app.blade.php --}}
    @sessionReplay
</body>
</html>

The directive renders a small config object and a deferred script. The script records one session per browser tab, carries it across page loads until the tab goes idle, and uploads a gzipped batch every few seconds.

How uploads stay safe without sessions

When the page renders, the server signs the current user, the tenant and any custom properties into a token using your app key. The recorder sends that token with each upload, so the ingest endpoint needs no session, cookie or CSRF token. The token is signed, not encrypted, so never put secrets in the custom properties.

Step 3: Lock down who can watch

This step matters most. Outside the local environment, nobody can view a recording until you define the viewSessionReplay gate. Add it to the published service provider:

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

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

The gate protects the recording list, the player and every file behind them. You can make it stricter. For example, you could let support staff see only sessions from their own tenant by checking properties on $session.

The built-in viewer lives at /session-replay. It has filters for sessions that contain errors or a user-reported problem.

Step 4: Record only when something goes wrong

Recording every session uses storage and raises privacy questions. In on_error mode the recorder keeps a rolling buffer in browser memory and uploads nothing until a trigger fires:

// config/session-replay.php
'mode' => 'on_error',

'on_error' => [
    'buffer_seconds' => 60,
    'triggers' => ['error', 'request'],
    'ask' => false,
],

When a JavaScript error or failed request happens, the recorder uploads the buffered minute and keeps recording for the rest of that tab’s session. You see what led up to the failure and what happened after it. Set ask to true if you want the user to agree before anything is sent. That is a good default for apps in regulated industries.

Step 5: Jump straight to the problem

The player timeline gets markers for:

  • uncaught JavaScript errors and console.error() calls
  • failed Livewire requests, and same-origin fetch or XHR calls that return 500 or higher
  • exceptions Laravel reports during a recorded request
  • page loads, wire:navigate swaps, and Inertia or Vue Router page changes
  • LCP, INP and CLS web vitals
  • rage clicks (three or more clicks on the same spot within 700 ms)

Click a marker and the player jumps to that moment. Server error markers also show the exception class, request method and path, and a report ID.

Custom markers and a “Report a problem” button

You can add your own markers from JavaScript, and send the current recording along with a user report:

// mark an important step in your flow
SessionReplay.mark('Checkout started', { cart: 3 });

// wire this to a "Report a problem" button
document.querySelector('#report-bug').addEventListener('click', () => {
    SessionReplay.send('Wrong total on the invoice');
});

This turns vague support tickets into recordings with a clear report marker.

Step 6: Link logs and error trackers to replays

While a recording is running, a global middleware adds the recording ID and viewer URL to Laravel’s Context. Laravel writes Context into every log entry for that request, so an error log looks like this:

production.ERROR: Undefined array key "total"
{"session_replay":"0b1c6a0e-…","session_replay_url":"https://app.test/session-replay/0b1c6a0e-…"}

Error trackers that read Context, such as Flare, Sentry and Nightwatch, receive the same keys. A session_replay_moment key opens the replay three seconds before the failing request. In the other direction, SessionReplay::logUrlUsing() adds an “Open in logs” button next to a server error’s report ID, pointing at a tool such as Log Viewer.

Step 7: Prune old recordings

The prune command deletes recordings after 30 days by default. Schedule it in routes/console.php:

use Illuminate\Support\Facades\Schedule;

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

Privacy checklist before production

  1. Keep input masking on. It is the default, so leave it unless you have a strong reason.
  2. Don’t record guests unless your privacy policy covers it.
  3. Review the gate so only the right staff can watch.
  4. Choose a private disk for the gzip chunks. Don’t use a public bucket.
  5. Update your privacy policy and cookie notice to mention session recording where the law requires it.
  6. Remember that Livewire’s wire:snapshot component state is removed before upload. Other data visible on the page is still captured, though, so check pages that show personal data.

Filament users

The companion package packstub/filament-session-replay adds a filterable recordings resource, the player, and a relation manager for your users inside a Filament v5 panel.

Takeaway

Session Replay gives Laravel teams the “watch the bug” workflow of hosted tools while the data stays on your own servers. Start with on_error mode, define the viewSessionReplay gate on day one, schedule pruning, and use the Context keys to jump from a log line straight to the moment things broke. Docs: Packstub Session Replay and the Packagist page.