freepeace13/inertia-live-laravel

Live Inertia pages driven by Spatie Event Sourcing projections. Declare once on the server which projection changes affect which page props; the package broadcasts a small "topic changed" signal and the client reloads only the affected props through the page's own controller.

The socket never carries model data, so policies, hidden attributes and per-user fields keep working unchanged.

Part of Inertia Live

Full documentation, a runnable demo and the client packages live in the main repository.

Requirements

• PHP 8.3, 8.4 or 8.5
• Laravel 12 or 13
• inertiajs/inertia-laravel ^2.0 or ^3.0
• spatie/laravel-event-sourcing ^7.14
• An Echo-compatible broadcaster (Reverb, Pusher or Ably)

Installation

composer require freepeace13/inertia-live-laravel

The service provider is auto-discovered. Optionally publish the config:

php artisan vendor:publish --tag=inertia-live-config

Broadcasting must be set up (php artisan install:broadcasting if it is not). See Installation.

Usage

1. Declare topics on events

use Freepeace13\InertiaLive\Attributes\LiveTopic;

#[LiveTopic('documents.{documentUuid}', props: ['document', 'activity'])]
final class DocumentRenamed extends ShouldBeStored
{
    public function __construct(
        public readonly string $documentUuid,
        public readonly string $title,
    ) {}
}

{placeholders} are filled from the event's scalar properties. The attribute is repeatable and is private unless its pattern is registered with Live::publicTopic(). See Topics.

2. Mark changes in projectors

use Freepeace13\InertiaLive\Concerns\EmitsLiveChanges;

final class DocumentProjector extends Projector
{
    use EmitsLiveChanges;

    public function onDocumentRenamed(DocumentRenamed $event): void
    {
        DocumentReadModel::whereUuid($event->documentUuid)->update(['title' => $event->title]);
    }
}

Signals are buffered, coalesced per topic and sent only after the handler returns and the database transaction commits. For events without the attribute, call $this->liveChanged('documents.'.$uuid, ['document']) inside a handler. See Projectors.

3. Authorize the topic

use Freepeace13\InertiaLive\Facades\Live;

Live::authorize('documents.{uuid}', fn (User $user, string $uuid) =>
    $user->can('view', Document::whereUuid($uuid)->firstOrFail())
);

Topics are broadcast on private channels (private-live.{topic}). A private topic without an authorizer fails closed: the signal is not sent and a warning is logged. See Authorization.

4. Bind the topic to props

return Inertia::render('Documents/Show', [
    'document' => DocumentResource::make($doc),
    'activity' => fn () => $doc->activity()->latest()->limit(20)->get(),
])->live("documents.{$doc->uuid}", only: ['document', 'activity']);

->live() adds a _live prop with the channel, bound props and current cursor. See Page bindings.

What the package provides

Correctness guarantees

The cursor store needs atomic increment (Redis, database, Memcached). See Consistency and Design decisions.

Configuration

// config/inertia-live.php
return [
    'enabled' => env('INERTIA_LIVE_ENABLED', true),
    'channel_prefix' => 'live',
    'cursor_store' => env('INERTIA_LIVE_CURSOR_STORE'), // null = default cache
    'max_signals_per_second' => 10,
    'replay' => ['suppress' => true, 'final_signal' => false],
    'debug' => env('APP_DEBUG', false), // logs every flushed signal
];

Invalid channel_prefix or max_signals_per_second values throw at boot. Details in Configuration.

Testing

use Freepeace13\InertiaLive\Facades\Live;

Live::fake();

$this->post(route('documents.rename', $doc), ['title' => 'Q4 plan']);

Live::assertChanged("documents.{$doc->uuid}", props: ['document']);
Live::assertNothingChangedFor('documents.other-uuid');
Live::assertChangedTimes("documents.{$doc->uuid}", 1);

See Testing.

Documentation

See the documentation index for installation, topics, projectors, authorization, consistency, configuration and troubleshooting.

Development

composer install
composer test      # Pest + Orchestra Testbench
composer lint      # Pint (use composer format to fix)
composer analyse   # PHPStan / Larastan

License

MIT