/laravel-reverb

name: laravel-reverb
description: Implement real-time WebSocket communication with Laravel Reverb. Use when adding live updates, chat, notifications, or presence features.
versions:
  laravel: "13.0"
  reverb: "1.12"
  php: "8.3"
user-invocable: false
references: references/channels.md, references/client.md
related-skills: laravel-architecture, laravel-queues

<objective> Covers Laravel Reverb, the first-party WebSocket server, for real-time features: broadcasting events from server to client, public/private/presence channel types and authorization, the Echo client-side listener, ShouldBroadcast queued delivery, and production deployment behind a reverse proxy with SSL. Use for live notifications, chat/messaging, live dashboards, and collaborative-editing whisper events — not for background/async work (that's laravel-queues). </objective>

Laravel Reverb

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:

1. **fuse-ai-pilot:explore-codebase** - Analyze existing broadcasting patterns 2. **fuse-ai-pilot:research-expert** - Verify Reverb docs via Context7 3. **mcp__context7__query-docs** - Check WebSocket and event patterns

After implementation, run **fuse-ai-pilot:sniper** for validation.

---

Overview

| Component | Purpose | |-----------|---------| | **Reverb Server** | First-party WebSocket server for Laravel | | **Broadcasting** | Send events from server to client | | **Channels** | Public, private, presence scoping | | **Echo** | Client-side event listener |

---

Decision Guide

Need real-time?
├── Live notifications → Reverb + private channel
├── Chat / messaging → Reverb + presence channel
├── Live dashboard → Reverb + public channel
├── Collaborative editing → Reverb + whisper
└── Background tasks → NOT Reverb (use Queues)

---

Quick Setup

php artisan install:broadcasting

BROADCAST_CONNECTION=reverb
REVERB_APP_ID=my-app
REVERB_APP_KEY=my-key
REVERB_APP_SECRET=my-secret
REVERB_HOST=0.0.0.0
REVERB_PORT=8080

---

Critical Rules

1. **Use private channels** for authenticated data 2. **Authorize channels** in `routes/channels.php` 3. **Use ShouldBroadcast** for queued delivery (recommended) 4. **Run Reverb behind Nginx/Caddy** in production with SSL

---

Reference Guide

| Need | Reference | |------|-----------| | Channel types, authorization | [channels.md](references/channels.md) | | Echo setup, client listeners | [client.md](references/client.md) |

---

Best Practices

DO

• Use `ShouldBroadcast` with queue for scalability
• Authorize private and presence channels
• Use presence channels for user awareness

DON'T

• Broadcast sensitive data on public channels
• Forget to configure CORS for cross-origin clients
• Expose Reverb directly without a reverse proxy

---

Laravel 13 Notes

Reverb 1.x (current 1.12) is **Laravel 13 compatible** with no changes. Notes:

• Broadcast events can be routed via `Queue::route(ShouldBroadcast::class, queue: 'events')` (see [[laravel-queues]])
• `Context::add()` is propagated automatically into broadcast events
• PHP: Reverb accepts PHP 8.2+, but Laravel 13 requires PHP 8.3 minimum
• Alternative: first-party **Mercure** driver (13.32+), installable via `php artisan install:broadcasting` (`--pretend` option in 13.33 to preview)