Skip to content
Tutorials Center
My learning

Topics

Lesson 134 of 147 Β· Projects

Project: Group Chat with Polling

Build a PHP group chat in five stages - messages in SQLite, JSON endpoints, polling with a since-id, safe escaping, rate limiting and a Server-Sent Events stream.

A chat room feels like magic the first time you build one: you type in one browser window and the message pops up in another. Under the hood, a simple chat is a list of messages in a database plus two questions the browser keeps asking the server: "here is a new message" and "anything new since the last one I saw?" Getting those two questions right is what this project is about, and the same pattern powers notification bells, live comment threads, order-status pages and dashboards.

You'll build the chat in five stages, each a complete program. First a message store in SQLite that can answer "everything after message 41" quickly and correctly. Then two JSON endpoints, and two simulated browsers that poll them. Then escaping, because a chat displays text typed by strangers, which makes it the textbook target for cross-site scripting. Then rate limiting, so one person can't flood the room. Finally a Server-Sent Events (SSE) version that pushes messages to the browser over one long-lived connection instead of asking again every few seconds. The project builds on Building a JSON API, PDO and the REST API project.

Our editor runs PHP on the command line, so there's no web server, no browser and no network. The demos simulate HTTP requests by calling the handler functions directly and print the responses, and the "browsers" are small PHP objects that act the way the JavaScript client would. The last sections show the real server and browser code, read-only.

The plan

The chat has rooms (general, random, …), and each room has one URL with two methods:

Request What it does Response
GET /rooms/{room}/messages?after=41 messages with an id greater than 41, oldest first, at most 50 200 with {"messages": [...], "last_id": 57}
POST /rooms/{room}/messages adds a message from a JSON body {"author": "...", "body": "..."} 201 with the stored message, 422 if invalid, 429 if too fast
GET /rooms/{room}/stream the SSE variant: an open connection that pushes new messages text/event-stream

There are four ways to get new messages to a browser, and it's worth knowing all of them before picking one:

Technique How it works Cost on a PHP server
Polling the browser asks every few seconds one short request per client per interval; simplest; up to one interval of delay
Long polling the server holds each request open until there is news (or 25 s pass) one PHP worker busy per waiting client
Server-Sent Events one long response; the server writes events into it as they happen one PHP worker busy per connected client
WebSockets a two-way connection upgraded from HTTP needs a separate long-running server process; PHP-FPM can't hold them

Polling is where you start: it works with every host, every proxy and every PHP setup, and with a cheap query behind it, a modest server can serve a lot of clients polling every few seconds. That's what stages 1 to 4 build. Stage 5 adds SSE for when you want messages to arrive instantly.

Stage 1: a message store with since-id queries

The heart of the chat is one table and one question: "which messages in this room have an id greater than N?" Each client remembers the highest id it has seen, and sends it with every poll. That's a cursor, and it's far more reliable than asking for "messages since 09:15:03":

  • Timestamps aren't unique. Two messages posted in the same second share a timestamp, and a client asking for "after 09:15:03" misses whichever one it hadn't seen yet.
  • Clocks disagree. The browser's clock, the web server's and the database's can be seconds apart.
  • With INTEGER PRIMARY KEY AUTOINCREMENT, SQLite guarantees ids only grow and are never reused, even after deletes. (Without AUTOINCREMENT, SQLite may reuse the id of a deleted last row. MySQL's AUTO_INCREMENT and PostgreSQL's identity columns also only grow.)

The index on (room, id) makes the query a short range scan no matter how many million messages the table holds, which matters because every client runs it every few seconds.

ChatStore::post() validates before it writes. Names are 1 to 30 letters, digits and a few punctuation marks (\p{L} and \p{N} with the u flag accept letters and digits from every script, so "Zoë" and "Łukasz" are fine). Bodies are trimmed and limited to 500 characters, counted with mb_strlen() because strlen() counts bytes and would cut off people who write in Greek or Japanese sooner. Control characters such as the terminal bell \x07 are rejected; line breaks are allowed. Note what is not done here: the text isn't escaped. The database stores exactly what the user typed, and stage 3 escapes it at output time, for each place it's shown.

PHP Stage 1: a message store with since-id queries

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Five bad posts are rejected: the empty string, and " ", which is empty after trimming; a 502-character message; a message containing the bell character; and the name <b>admin</b>, which contains characters that aren't allowed in names. Ana and Ben's messages were posted in the same second, and both are still found and ordered correctly by id.

latest() is what a client calls when it first opens a room: the newest 50 messages, but in chronological order. The inner query takes the newest ones (ORDER BY id DESC LIMIT 50), and the outer query puts them back in ascending order. After that, the client remembers the last id (4 here) and only ever asks for what came after it. Message 3 is in #random, so it never shows up in #general.

Stage 2: JSON endpoints and two polling clients

Now the store gets an HTTP face. handle() takes a method, a URL and a body, and returns a status, headers and a JSON body, just like the router in the REST API project, but small enough to read in one go:

  • The room name comes from the path and must match [a-z0-9-]{1,30}, so a path like /rooms/../etc/messages is a plain 404.
  • after is validated with filter_var(..., FILTER_VALIDATE_INT) and a minimum of 0. A missing value means 0: "everything".
  • Every response sends Cache-Control: no-store. A browser or proxy that cached a poll response would show stale messages forever.
  • The response includes last_id, the cursor for the next poll. When nothing is new, it's the same after value the client sent, so the client never goes backwards.
  • array_last(), new in PHP 8.5, returns the last element of an array (here, the newest message).

The two Client objects play the browsers. Each one keeps its cursor (lastId) and a list of message ids already on screen. When you send a message, the response contains the stored message, so the client shows it immediately. The next poll returns that message again (its id is above the cursor), and the client skips it because it's already shown. Don't "fix" this by moving the cursor to your own message's id: if someone else posted while your request was on its way, their message would have a lower id and you'd skip it forever.

PHP Stage 2: JSON endpoints and two polling clients

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Read the output as a timeline. Ana's first poll is empty. Ben's first poll gets Ana's question; Ana's next poll gets Ben's answer, but not her own message, which she already displayed when she posted it. The last two polls find nothing new. In the edge cases, a negative cursor and a body without body are 400 (the request itself is malformed), a whitespace-only message is 422 (well-formed but invalid), and an unsupported method is 405 with an Allow header.

At most 50 messages come back per poll. If a client was offline for a while and gets a full page of 50, it should poll again right away instead of waiting for the next interval, until a poll returns fewer than 50.

Stage 3: escaping, and the browser side

A chat shows text written by strangers to everyone else in the room, so if one message can inject HTML, it runs in every reader's browser: it can read their page, post as them, or redirect them. The rule from XSS and Output Escaping applies exactly: store raw text, and escape it for the context where you output it. A chat has three such contexts:

  1. JSON for the polling client. json_encode() produces a valid JSON string, but JSON isn't HTML. The JavaScript must insert the text with textContent, never innerHTML.
  2. HTML rendered by PHP, for the first page load or a no-JavaScript version: htmlspecialchars() on every value, then nl2br() to show line breaks. The order matters: escape first, then add the <br> tags.
  3. JSON inside a <script> tag, a common trick to send the initial messages with the page. Here htmlspecialchars() is wrong (it would show &lt; in the chat) and plain json_encode() is dangerous, because the string </script> ends the script block early. The JSON_HEX_* flags encode <, >, &, ' and " as <-style escapes, which mean the same characters to JavaScript but can't break out of the tag.
PHP Stage 3: escaping messages for every context

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

In the server-rendered HTML, Mallory's <img> tag is shown as harmless text, and Ana's line break became a <br> after escaping. In the last part, the "unsafe" line contains </script><script>steal()</script> literally: a browser would end the first script there and run Mallory's. The "safe" line has the same data with every dangerous character as a \u escape.

Here is the browser side of polling. It renders with textContent, polls again 3 seconds after each response (not with setInterval, so slow responses never pile up), backs off when the server is unhappy, and slows down while the tab is hidden:

JavaScript
const room = 'general';
const list = document.querySelector('#messages');
const shown = new Set();
let lastId = 0;
let delay = 3000;

function show(message) {
  if (shown.has(message.id)) return;   // already on screen (our own message, for example)
  shown.add(message.id);
  const item = document.createElement('li');
  const name = document.createElement('b');
  name.textContent = message.author;   // textContent: never interpreted as HTML
  const text = document.createElement('p');
  text.textContent = message.body;     // CSS "white-space: pre-line" shows the line breaks
  item.append(name, text);
  list.append(item);
}

async function poll() {
  try {
    const response = await fetch(`/rooms/${room}/messages?after=${lastId}`);
    if (response.status === 429) {
      delay = Number(response.headers.get('Retry-After') ?? 10) * 1000;
    } else if (response.ok) {
      const data = await response.json();
      data.messages.forEach(show);
      lastId = data.last_id;
      delay = data.messages.length === 50 ? 0 : 3000;   // a full page: fetch the rest now
    } else {
      delay = Math.min(delay * 2, 60000);               // server trouble: back off
    }
  } catch {
    delay = Math.min(delay * 2, 60000);                 // offline: back off
  }
  setTimeout(poll, document.hidden ? Math.max(delay, 15000) : delay);
}

poll();

Sending a message is a fetch() with method: 'POST', a JSON body and a Content-Type: application/json header. Pass the stored message from the 201 response to show(). Then clear the input box only after the server accepted the message, so a 422 or 429 doesn't throw away what the user typed.

Stage 4: rate limiting

Without limits, one script can post a thousand messages a second, which floods the room for everyone and fills your database. A rate limiter counts requests per key (a user, an IP address, or both) and answers 429 Too Many Requests when a key goes over its budget, with a Retry-After header saying how many seconds to wait.

This limiter uses a fixed window: time is cut into 10-second windows, and each key may make 5 requests per window. The counting happens in one atomic SQL statement, an UPSERT (INSERT ... ON CONFLICT DO UPDATE): it inserts a counter for a new key, or adds one to an existing counter if it belongs to the current window, or restarts it at 1 if the window has moved on. Because it's one statement, two simultaneous requests can't both read "4" and both write "5". In the UPDATE part, excluded.window_start means "the value the INSERT tried to write", and the plain column names refer to the existing row. The current time is passed in as a number, so the demo can run 12 seconds of traffic instantly.

PHP Stage 4: rate limiting with 429 and Retry-After

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The spammer's first five messages in the window go through; the next five are rejected, and Retry-After counts down to the start of the next window, where the budget resets. Ana, a different user on a different IP address, is unaffected. Rejected attempts also count as hits, so a client that ignores Retry-After and keeps hammering stays blocked.

Fixed windows are simple, but they allow a burst at the edges: 5 requests at second 9 and 5 more at second 10 are 10 requests in two seconds. If that matters, use a sliding window (count the timestamps of the last 10 seconds) or a token bucket (a budget that refills steadily). On a busy site, keep the counters in Redis (INCR plus EXPIRE) instead of the main database, so rate limiting never adds write load to it. Polling requests need a limit too, but a generous one, such as 60 per minute per IP; only abuse should ever hit it.

Stage 5: pushing messages with Server-Sent Events

Polling has an unavoidable delay: a message posted just after a poll waits up to one interval. Server-Sent Events remove it. The browser opens one request with new EventSource(url), and the server keeps the response open and writes events into it whenever there's something new. The format is plain text:

  • id: 42 sets the event's id. When the connection drops, the browser reconnects automatically and sends the last id it received in a Last-Event-ID header. That's the same since-id cursor as in polling, handled by the browser for you.
  • event: message names the event type, and data: ... carries the content. A blank line ends the event.
  • retry: 2000 tells the browser how many milliseconds to wait before reconnecting.
  • A line starting with : is a comment. Sending one now and then keeps proxies from closing an idle connection.

The stream function checks the database once per second and writes any new messages. It ends after a fixed time on purpose; the browser reconnects, and each PHP worker is freed regularly. In the demo, the clock and the network are fakes: $sleep lets other users post at seconds 3 and 4, and $send prints instead of writing to a socket.

PHP Stage 5: a Server-Sent Events stream

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The first connection receives the existing message right away and the two new ones as they're posted. Chen's multi-line message stays on one data: line because json_encode() writes the line breaks as \n. A raw line break would end the field, so if you ever send plain text instead of JSON, prefix every line with its own data:. After 10 quiet seconds, a keep-alive comment goes out. Ben's message arrives while the browser is reconnecting, and since the second connection starts from Last-Event-ID: 3, nothing is lost or repeated.

On a real server, the endpoint sets the headers, closes the session and flushes after every write:

PHP
<?php

declare(strict_types=1);

session_start();
$user = $_SESSION['user'] ?? null;   // read what you need from the session...
session_write_close();               // ...then release its lock (see below)

header('Content-Type: text/event-stream');
header('Cache-Control: no-store');
header('X-Accel-Buffering: no');     // ask nginx not to buffer the stream

while (ob_get_level() > 0) {
    ob_end_flush();
}

$lastEventId = filter_var($_SERVER['HTTP_LAST_EVENT_ID'] ?? 0, FILTER_VALIDATE_INT) ?: 0;
set_time_limit(40);

streamMessages(
    $db,
    $lastEventId,
    30,
    function (): void {
        sleep(1);
        if (connection_aborted()) {  // the user closed the tab
            exit;
        }
    },
    function (string $chunk): void {
        echo $chunk;
        flush();                     // push it to the browser now
    },
);
JavaScript
const source = new EventSource('/rooms/general/stream');
source.addEventListener('message', (event) => show({ id: Number(event.lastEventId), ...JSON.parse(event.data) }));
source.addEventListener('error', () => console.log('Connection lost, the browser will retry'));

Release the session lock. PHP's default file sessions lock the session for the whole request. A stream that runs for 30 seconds with the session open blocks every other request from the same user, including posting a message, for those 30 seconds. Read what you need, then call session_write_close(). The same applies to long polling.

The cost is the important part. With PHP-FPM, every open SSE connection occupies one PHP worker for its full duration. A server with 50 workers can hold at most 50 listeners, and then the rest of the site stops answering. SSE in plain PHP is fine for an internal tool or a small community. For thousands of listeners, keep PHP for posting messages and hand the delivery to a process built for many idle connections: an event-loop server such as ReactPHP, Swoole or a Mercure hub, or a hosted real-time service. Your PHP code then just publishes "new message in #general" to it.

Running it on a real server

On a server, a front controller calls the same handle() function with the real request, and sends what it returns:

PHP
<?php

declare(strict_types=1);

require __DIR__ . '/../src/chat.php';   // ChatStore, RateLimiter, handle()

[$status, $headers, $body] = handle(
    $store,
    $_SERVER['REQUEST_METHOD'],
    $_SERVER['REQUEST_URI'],
    file_get_contents('php://input'),
    new DateTimeImmutable(),
);

http_response_code($status);
foreach ($headers as $name => $value) {
    header("$name: $value");
}
echo $body;

Three things change compared with the demos:

  • The author comes from the login, not the request. In the demo, the JSON body says who is speaking, which means anyone can post as anyone. On a real site, take the name from the session set up by the login system, and ignore any author field.
  • Posting needs CSRF protection. If the chat uses session cookies, a malicious page could make a logged-in visitor's browser post messages. Send a CSRF token in a request header such as X-CSRF-Token and check it in handle().
  • Pass the real client IP to the rate limiter. Use $_SERVER['REMOTE_ADDR']. Behind a load balancer or CDN, it's the proxy's address; read the forwarded header your proxy sets, but only when the request really came from that proxy, because anyone can send an X-Forwarded-For header.

Old messages pile up forever, so a daily command-line job can delete messages older than, say, 90 days. Thanks to AUTOINCREMENT, deleting never causes an id to be reused, so cursors stay valid.

Ideas for extending the chat

  • Typing indicators ("Ben is typing…"): a short-lived row per user and room, updated at most every few seconds, returned alongside messages in the poll response.
  • Unread counts per room: store each user's last-read id per room; unread is COUNT(*) WHERE id > last_read.
  • Editing and deleting: add edited_at and deleted_at columns, and an updated_after cursor so clients learn about changes to old messages too.
  • Mentions and links: after escaping, turn @name and URLs into links with preg_replace_callback(), escaping the parts you insert again.
  • Moderation: a banned_until column checked in post(), and a word filter that flags messages for review instead of silently changing them.
  • Tests: ChatStore, RateLimiter and handle() take their database and time as arguments, so they're easy to cover with the tools from Testing.

Check your understanding

Quick check Β· 5 questions

of 5 answered You scored / 5 Β· perfect!

  1. 1. Why does the client send the highest message id it has seen instead of the time of its last poll?

    With AUTOINCREMENT, every new message gets a higher id than all earlier ones. A time cursor would miss a message posted in the same second as the last one seen, or be thrown off by clock differences.
  2. 2. Ben posts a message and gets back id 57. Why shouldn't his client set its cursor to 57 straight away?

    Other people's messages can be stored between Ben's last poll and his post. The client keeps polling from its old cursor and skips ids it has already shown.
  3. 3. Which is the safe way to put a message's text into the page with JavaScript?

    textContent inserts text, so tags in the message are shown literally instead of being run. The other three parse the text as HTML.
  4. 4. The rate limiter allows 5 messages per 10-second window. A client posts at seconds 0 to 6. What happens at second 6?

    Seconds 0 to 4 use the five allowed messages, so the attempts at seconds 5 and 6 are rejected. The window ends at second 10, which is 4 seconds after second 6.
  5. 5. An SSE endpoint keeps each connection open for 30 seconds. What is the main cost of this on a PHP-FPM server?

    A PHP-FPM worker serves one request at a time. SSE and long polling hold requests open, so they use up workers; polling uses them only briefly.

Summary

  • Store chat messages with an AUTOINCREMENT id and an index on (room, id); clients poll with the highest id they've seen (?after=41) and the server returns last_id as the next cursor.
  • Show your own message from the POST response right away and skip ids already on screen, rather than moving the cursor.
  • Validate names and bodies (length in characters with mb_strlen(), no control characters), store the raw text, and send Cache-Control: no-store on poll responses.
  • Escape per context: textContent in JavaScript, htmlspecialchars() then nl2br() in HTML, and JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT for JSON inside <script>.
  • Rate-limit posting per user and per IP with an atomic UPSERT counter, answering 429 with Retry-After; clients back off on errors and poll less often in hidden tabs.
  • Server-Sent Events push messages over one response (id:, event:, data:, retry:), with automatic reconnects through Last-Event-ID. Call session_write_close() and flush(), keep connections short, and remember that each connection occupies a PHP worker.

Next: PHP Cheat Sheet