1: phloWS overview
phloWS is the realtime layer of the Phlo platform. It lets a Phlo app push to connected browsers over WebSockets without you leaving the Phlo language: you write the same .phlo handlers you already write, and a small Node broker runs one compiled handler per event.
1.1: The model
A single Node process, the broker, owns the WebSocket connections. When a client connects, authenticates, sends a message or disconnects, the broker invokes your Phlo app once for that event, the same way an HTTP request does. Your handler runs, optionally broadcasts, and exits. There is no long-lived PHP process holding sockets open.
- One broker per app handles every socket.
- One compiled handler per event: connect, auth, receive, close.
- Stateless handlers: each event is a fresh, short-lived invocation, just like a route.
This keeps the realtime code in the same mental model as the rest of Phlo: short handlers, explicit state in the database, no special runtime to reason about.
1.2: When to use it
Use phloWS when the browser needs to be told about something it did not ask for: live counters, presence, chat, notifications, dashboards, collaborative state. If a plain async form round-trip is enough (the Poll tutorial works this way), you do not need phloWS at all. phloWS is an additive step: an app keeps working without the broker, and lights up with realtime when the broker is running.
1.3: What you wire
- A
websocket:port in your app entrypoint and theDOM/websocketresource for the browser client. - The body class
wss, which is the switch that tells the client to open a socket. - Four hooks (next chapter) and
wsCastto broadcast.
The phlo-demo-websocket repository is a working reference for all of this in source form, and it continues directly from the Poll tutorial.