Mercure Basics

SO FAR, a client learns of changes ONLY when it ACTIVELY asks (polling) – Mercure delivers updates in REAL TIME, WITHOUT the client having to ask repeatedly.

What is Mercure?

Mercure is an OPEN protocol standard BUILT ON Server-Sent Events (SSE) – a client opens ONE long-lived HTTP connection to a "hub", the connection stays OPEN, and the server sends updates AS SOON AS they occur.

The hub in the Docker Compose setup

The api-platform distribution ALREADY ships with a Mercure hub as its OWN container (compose.yaml, the mercure service) – NO additional installation needed, UNLIKE with JWT (chapter 48).

docker compose ps mercure

.env (excerpt)

MERCURE_URL=https://php/.well-known/mercure
MERCURE_PUBLIC_URL=https://localhost/.well-known/mercure
MERCURE_JWT_SECRET="!ChangeThisMercureHubJWTSecretKey!"

Achtung: EXACTLY like the JWT secret in lexik_jwt_authentication.yaml (chapter 48), MERCURE_JWT_SECRET MUST be replaced with a REAL, randomly generated value for a PRODUCTION system.

Hub vs. API: two separate responsibilities

Component	Responsibility
The Symfony/API Platform application	GENERATES updates (e.g. "Project 1 was changed") and PUBLISHES them to the hub
The Mercure hub	DISTRIBUTES published updates to ALL clients that have SUBSCRIBED to the matching "topic"

This SEPARATION is DELIBERATE: the hub is a SELF-CONTAINED, generic component that could ALSO be used by completely DIFFERENT applications (not just Symfony/PHP).

Topics explained

A topic is SIMPLY a URI that identifies a "message category" – EXACTLY like a channel name in pub/sub systems. API Platform uses the resource's IRI as the topic BY DEFAULT (chapter 68 shows this CONCRETELY), e.g. /api/projects/1.

Tipp: Mercure is DELIBERATELY NOT LIMITED to API Platform – the EXACT SAME hub infrastructure could ALSO be used by a COMPLETELY independent script (e.g. a cron job) to PUBLISH updates; this chapter, however, focuses on the API Platform integration.