Pollsockets Laravel Laravel Package

Getting Started

PollSockets replaces a hosted WebSocket provider with an HTTP polling transport. The shortest path from zero to a delivered event:

1. composer require pollsockets/pollsockets-laravel
2. Publish and run the package migrations — messages are persisted, so the tables must exist before anything broadcasts.
3. Publish the config file and wire the package's broadcast driver in place of your current one, or use the PollSocket facade directly if you only need targeted pushes.
4. Include the JS client in your front end, point it at your app's origin, and start it with a channel subscription.
5. Fire a test event from php artisan tinker and confirm the client receives it before touching application code.

First real use case: order status / notification badges. Anything where a few seconds of latency is acceptable and you'd rather not run a separate WebSocket server or pay per-connection pricing.

New in 2.0: the cursor is now millisecond-precision, and the server tracks a client origin. Both are relevant to your very first setup — decide up front which origins your app will poll from, because a mismatched origin is the most common cause of "the event fires but the client never sees it."

Implementation Patterns

Event broadcasting. Keep using Laravel's standard broadcasting API (broadcast(new OrderShipped($order))->toOthers()). The package is a transport swap, not a new event system — resist the urge to call the facade directly everywhere, since that makes it painful to switch transports later.

Cursor as resumable state. The client sends a cursor and receives everything after it. Treat that cursor as durable client state: persist it in sessionStorage (or localStorage for cross-tab continuity) so a page reload doesn't replay or skip messages. In 2.0 the cursor value is a millisecond timestamp — any cursor you persisted from 1.x is in a different unit and must be discarded, not migrated.

Client origin for multi-surface apps. If you serve the same backend to a web app, an admin panel, and a mobile web view, 2.0's client origin lets you keep those message streams distinguishable. Set it explicitly per surface at client init rather than relying on whatever the browser sends — it keeps server-side filtering predictable and makes logs readable.

Polling cadence. Tune the interval against your traffic profile. A 5s interval on a dashboard with 50 concurrent users is trivial; the same interval on a public page with 20k concurrent users is a load problem. Prefer longer intervals plus event-driven refresh, and consider backing off when the tab is hidden.

Integration with existing auth. Private/presence-style channels should reuse your existing guards. Don't invent a second auth path in the package's channel authorization callback — call into the same policy or gate you use for the page itself, so permission changes take effect immediately rather than at next poll.

Testing. Because the transport is HTTP, you can assert on broadcasting with Event::fake() as usual, and exercise the polling endpoint with normal feature tests. That's a genuine advantage over WebSocket transports — lean on it.

Gotchas and Tips

The 2.0 cursor unit change is a breaking one. Any client code that parses, stores, or synthesizes a cursor itself will break. If you have a custom JS client rather than the shipped one, audit it: comparisons like cursor + 1 or Math.floor(cursor / 1000) are now wrong by three orders of magnitude. Symptoms are subtle — either a flood of duplicate deliveries or a silent gap.

Client origin mismatches fail quietly. The event is written, the poll returns 200, and nothing shows up. When debugging "missing" events, check origin before anything else: log what the client sends, compare it to what the broadcast was tagged with, and confirm your config doesn't filter origins. Add an explicit allowlist rather than wildcarding, so the failure is loud.

Message table growth is your problem. Nothing prunes old rows by default in most setups. Schedule the package's cleanup command, or write one, and monitor table size — an unpruned messages table turns into a slow query and a disk alarm months later, long after the deploy that caused it.

Broadcast dispatch is not instant if queued. If your events implement ShouldBroadcast, they go through the queue. A stopped worker looks identical to a broken transport from the user's perspective. Check failed_jobs and the queue worker before touching package config.

Poll request volume, not poll count, is the metric. Each poll is a full HTTP request through your stack: middleware, session, DB. Watch it at the web server layer. Behind a load balancer with short idle timeouts, keep-alive settings matter more than you'd expect.

Extension point worth knowing: the message store and the origin resolution are the two seams most worth overriding if your needs diverge from the defaults. Subclass or rebind them in a service provider rather than forking the package — that keeps future upgrades (including the next cursor change) as a composer update.

Upgrade path from 1.4: bump the constraint, clear config cache, redeploy, and force a client-side cursor reset (clear the persisted cursor key or version it). Plan a coordinated front-end/back-end release — a new backend with old client code is exactly the mismatch described above.