Laravel Reverb Kit

Developed and maintained by IntrAgile Kft.

Magyar leírás

Production toolkit for Laravel Reverb when you run it yourself, in Docker, Swarm or compose, behind your own reverse proxy:

• reverb:doctor, a static deploy gate. It catches the configuration mistakes that make real-time updates silently stop: a bind address used as the publish target, a hostname given to the server to bind to, a lost path prefix, replicas without scaling, a shared scaling channel, contradicting size limits, a vulnerable Reverb release. It exits non-zero and has a --json output. The same rules show up in laravel/doctor under the reverb group.
• Generators for the configuration you would otherwise copy between projects:
  • reverb:proxy nginx|caddy|traefik, the WebSocket reverse proxy;
  • reverb:stack swarm|compose, the Reverb service;
  • reverb:env, the env block that keeps the three Reverb hosts apart.
• An opt-in payload size guard. It checks every broadcast before it is sent. Without it, Reverb rejects a publish over its request limit with a 413 that surfaces as a generic BroadcastException, often in a queue worker, far from the code that caused it.

If you deploy with Laravel Forge, Forge configures the proxy and the daemon for you; the doctor is still useful, the generators are not.

Requirements

• PHP 8.3+
• Laravel 12 or 13

Optional packages

Installation

composer require intragile/laravel-reverb-kit

The service provider is discovered automatically. To change the defaults, publish the configuration:

php artisan vendor:publish --tag=reverb-kit-config

The three hosts

Most Reverb deployment failures come from mixing up three different hosts:

                      VITE_REVERB_HOST:443 (https)
  Browser ──────────────────────────────────▶ reverse proxy ──▶ Reverb server
                                                 /app/{key}      binds REVERB_SERVER_HOST:REVERB_SERVER_PORT
                                                                 (0.0.0.0:8080)
                                                                      ▲
  Laravel application ────────────────────────────────────────────────┘
                      REVERB_HOST:REVERB_PORT (http, internal network, e.g. reverb:8080)

• REVERB_SERVER_HOST is where the server listens: an IP, usually 0.0.0.0. Nobody connects to it.
• REVERB_HOST / REVERB_PORT / REVERB_SCHEME are where Laravel sends broadcasts. In a container setup this is the service name on the internal network, for example reverb:8080 over http.
• VITE_REVERB_HOST / _PORT / _SCHEME are what the browser connects to: the public hostname, through the proxy and TLS. They are baked into the frontend bundle at build time.

php artisan reverb:env prints this block with comments.

Doctor

php artisan reverb:doctor

  OK    connection-credentials The connection credentials match the Reverb app 1.
 FAIL   publish-target         The reverb connection host is a bind address (0.0.0.0).
                                → REVERB_HOST is where Laravel sends broadcasts; the bind address belongs in REVERB_SERVER_HOST.
  OK    server-bind            Reverb binds to 0.0.0.0
  OK    scaling                scaling off, 1 replica
 WARN   allowed-origins        Reverb app(s) 1 accept connections from any origin
  ...
1 failed, 1 warning(s), 7 ok, 1 skipped.

Exit codes: 0 when nothing failed (warnings included, unless --strict), 1 on a failure, 2 on invalid options. When the default broadcasting connection is not the Reverb one (for example null in an application that does not broadcast), every rule is skipped and the exit code is 0.

As a deploy gate

Run it where the deployed configuration is available, for example as a step after the configuration is rendered and before traffic is switched:

php artisan reverb:doctor --replicas="$REVERB_REPLICAS" --frontend-env=frontend/.env

Rules

The doctor is static: it reads configuration and makes no network calls. For a live WebSocket round trip, see intragile/laravel-observability, whose BroadcastCheck sends an event through Reverb and waits for it on a real connection.

laravel/doctor

With laravel/doctor installed, each rule is a diagnostic in the reverb group:

php artisan doctor --only=reverb

Generators

Every generator prints to stdout, or writes a file with --output= (an existing file is only overwritten with --force). Values come from your configuration; options override them.

Reverse proxy

php artisan reverb:proxy nginx --public-host=ws.example.com
php artisan reverb:proxy caddy
php artisan reverb:proxy traefik

The nginx location resolves the upstream through Docker's DNS (resolver 127.0.0.11) and a variable proxy_pass. With a literal host name nginx resolves it once, at startup, and keeps proxying to the old address after the orchestrator reschedules Reverb. The read timeout is twice the ping interval, so idle connections are not cut at nginx's 60 s default. The location matches /app/ only; --with-api also exposes the HTTP API under /apps/, which is only needed when the publisher runs outside the network.

Swarm and compose service

php artisan reverb:stack swarm --image=registry.example.com/app:1.4.0 --replicas=1
php artisan reverb:stack compose --image=registry.example.com/app:1.4.0

The service runs reverb:start from your application image, publishes no ports, checks health on Reverb's /up endpoint (falling back to a status code check for releases without it), and limits resources. With one replica it updates stop-first: two instances without scaling would split the clients between them. With more than one replica it turns scaling on, updates start-first and picks a scaling channel derived from the application name unless you pass --scaling-channel.

Env block

php artisan reverb:env --public-host=ws.example.com --internal-host=reverb

Custom templates

php artisan vendor:publish --tag=reverb-kit-stubs

The stubs are copied to stubs/reverb-kit/; a published stub takes precedence over the package's own.

Payload size guard

Opt in with REVERB_KIT_GUARD_PAYLOADS=true. The guard wraps the reverb broadcast driver and measures every publish request exactly as the Pusher client would send it, before anything is sent. The size includes the channel list and, for private-encrypted-* channels, the ciphertext.

Broadcast "OrderShipped" is 10342 bytes, over the 10000-byte Reverb request limit (raise REVERB_MAX_REQUEST_SIZE or send less).

A broadcast split into several requests (more than 100 channels, or encrypted channels) goes out to all of its channels or to none. Laravel's ShouldRescue still applies on top: the guard decides whether a payload is sent, ShouldRescue decides what happens to any other broadcasting error.

Channel isolation between deployments

Reverb isolates apps by their key, so deployments with their own REVERB_APP_* credentials do not see each other's channels. What they can share is the scaling channel: give every deployment its own REVERB_SCALING_CHANNEL, for example reverb_{app}_{environment}, and set REVERB_KIT_SHARED_REDIS=true where several deployments use one Redis so the doctor enforces it.

What happens when something is not installed

Configuration reference

See config/reverb-kit.php. Environment variables: REVERB_KIT_CONNECTION, REVERB_KIT_SERVER, REVERB_KIT_REPLICAS, REVERB_KIT_SHARED_REDIS, REVERB_KIT_FRONTEND_ENV, REVERB_KIT_GUARD_PAYLOADS, REVERB_KIT_ON_OVERSIZE, REVERB_KIT_UPSTREAM_HOST, REVERB_KIT_PUBLIC_HOST.

Testing

composer test
composer analyse

License

MIT. See LICENSE.

Developed and maintained by IntrAgile Kft.