Download the PHP package gramercytech/laravel-claim-check without Composer

laravel-claim-check

Bypass Pusher's 10KB broadcast payload limit (and similar limits on other broadcasters) using the claim-check pattern: oversized messages are stored server-side in a cache and replaced with a small stub. Clients transparently fetch the full payload on receipt — your application code doesn't change.

Status: v0.1.0 · scaffold complete, integration-tested, not yet published.

Why

Pusher Cloud caps broadcast payloads at 10KB. As applications grow — AI streaming, rich notifications, large change events — that limit is hit sooner than expected, often without warning, and Pusher silently drops the message. Reducing payload size per-event is fine for one or two cases, but doesn't scale.

This package solves the problem at the broadcaster layer:

• Every outgoing broadcast is measured.
• If under the threshold (default 8KB), it's sent as-is.
• If over, the payload is stored in a cache, and a tiny stub is sent in its place: { _cc: 1, u, id, e }.
• The companion JS package (@gxp-dev/laravel-claim-check) wraps Echo to detect stubs, fetch the full payload, and forward it to your listener.

The pattern is broadcaster-agnostic — it works with Pusher, Ably, Reverb, Soketi, or anything you can wrap.

Install

In your .env:

That's it. The package auto-registers a claim-check connection so you don't need to touch config/broadcasting.php at all — your existing Pusher (or other) connection is wrapped via the inner setting in config/claim-check.php.

⚠️ Match your /broadcasting/auth middleware. The fetch endpoint defaults to ['web'], which only works for classic session-authenticated apps. If your BroadcastServiceProvider does Broadcast::routes(['middleware' => ['web', 'auth:sanctum']]) (the usual setup for Inertia / Sanctum / SPA apps), set the same middleware in config/claim-check.php under route.middleware. Otherwise $request->user() will be null when your channel auth callbacks run and every fetch will 403.

Multiple claim-check connections (optional)

If you want more than one (e.g. a low-threshold connection for chat and a high-threshold one for analytics), explicitly add them to config/broadcasting.php — any setting from config/claim-check.php can be overridden per-connection:

Switch via BROADCAST_DRIVER=pusher-cc-aggressive.

Configure

config/claim-check.php:

Every key can also be overridden per-connection in config/broadcasting.php — see "Multiple claim-check connections" above.

Event filter precedence

Events are matched against whatever string Laravel passes as the broadcast event identifier — by default the FQCN, or the return value of broadcastAs() if your event implements it.

The four lists are applied in this order:

1. Allow — if non-empty and the event is not in it, pass through unchanged.
2. Skip — if the event is in skip, pass through unchanged.
3. Always — if the event is in always, claim-check (ignore size).
4. Threshold — claim-check when payload size exceeds the threshold.

Implications:

• Skip overrides always.
• Always does not bypass the allow filter — if you set an allow list, it's a strict whitelist for everything claim-check ever applies to.
• Setting threshold: 0 and leaving the lists empty claim-checks every non-empty broadcast on the connection.

How it works

Security

• Claim IDs are 128-bit random. Unguessable in practice.
• Channel binding. A claim is only fetchable if the requested channel was a recipient of the original broadcast. Knowing the id of a claim bound to private-admin.123 does not let a user fetch it via private-user.456.
• Channel authorization. For private-* and presence-* channels, the fetch endpoint re-runs the same channel auth callbacks Laravel uses for /broadcasting/auth. Public channels are not authorized — same as the underlying Pusher delivery.
• Encrypted channels. Not claim-checked by default; the client-side decryption pipeline does not handle fetched payloads cleanly. Oversized encrypted payloads pass through untouched and will be rejected by Pusher (with a warning logged).

If you need rate-limiting or additional auth on the fetch endpoint, add your own middleware via config('claim-check.route.middleware').

Frontend

See js/README.md for the companion npm package.

Testing

Tests use Pest 2/3 + Orchestra Testbench. A spy broadcaster is used as the inner driver so assertions can inspect what would have been sent to Pusher.

Roadmap (post-v1.0)

• Telescope panel for inspecting claim-checked broadcasts
• Metrics hooks (claims created, fetched, expired, evicted)
• Built-in support for re-entering Echo's encryption pipeline on fetched payloads (so encrypted channels can be claim-checked safely)
• Optional inline encryption of cached payloads at rest

Releasing

Maintainers: see RELEASING.md for the cut-a-release runbook and the one-time Packagist/npm setup.

License

MIT — see LICENSE.md.