1: Phlo Realtime overview

Phlo Realtime 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 the Phlo Daemon hands each socket event to your app, as a fresh process per event or through a resident worker pool when you need the throughput.

1.1: The model

Phlo Realtime is the WebSocket layer built into the Phlo Daemon: the one daemon process owns the socket connections. When a client connects, authenticates, sends a message or disconnects, the daemon runs your app for that event the same way an HTTP request does, dispatching it in-process onto its own worker pool. Your handler runs, optionally broadcasts, and returns. The sockets and the PHP live in the same process: no separate service, no extra network hop.

• One process (the daemon) serves the sockets for every app on the machine.
• One handler call per event: connect, auth, receive, close.
• Stateless handlers: each event is its own clean 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.

The daemon runs each host in one of two modes (see the WebSocket guide): one-shot, a fresh PHP process per event (a build: true app, ideal for development and its hot-reload), or a resident worker pool (a release app) that boots the app once for production throughput. The mode follows the app's build flag, not a config entry. The handler code is identical; in pool mode the app is resident and phlo('tech/reset') clears per-event state between calls, so write worker-safe handlers (no request or user state in statics, commit or roll back DB work) either way.

1.2: When to use it

Use Phlo Realtime 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 Phlo Realtime at all. Phlo Realtime is an additive step: an app keeps working without realtime, and lights up when the daemon is running.

1.3: What you wire

• A daemon: port in your app entrypoint and the DOM/websocket resource 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 wsCast to broadcast.
• One running service: the Phlo Daemon, which owns the sockets and runs the hooks.

The phlo-demo-poll repository is a working reference for all of this in source form: the poll now carries Phlo Realtime, continuing directly from the Poll tutorial.