Everything You Need to Know to Master Server-Sent Events (SSE) in Symfony 7.4

I often see teams reach for WebSockets (via Socket.io or Pusher) when they simply need to update a UI with server-side state changes. While WebSockets are powerful, they are often overkill. If your requirement is unidirectional (Server → Client) — like stock tickers, progress bars, or notification feeds — Server-Sent Events (SSE) is the protocol you should master. WebSockets Server-Sent Events (SSE) SSE runs over standard HTTP/1.1 or HTTP/2. It doesn’t require complex handshakes, works with standard authentication mechanisms, and native support is built into every modern browser via the EventSource API. EventSource API In this guide, we will implement SSE in Symfony 7.4 using two approaches: The Native Approach: Using StreamedResponse (Great for understanding the protocol and simple, low-concurrency tasks). The Production Approach: Using the Mercure protocol (The scalable, non-blocking standard for Symfony). The Native Approach: Using StreamedResponse (Great for understanding the protocol and simple, low-concurrency tasks). The Native Approach: The Production Approach: Using the Mercure protocol (The scalable, non-blocking standard for Symfony). The Production Approach: Mercure The Native Approach (StreamedResponse) Symfony’s StreamedResponse allows you to keep an HTTP connection open and flush data to the client incrementally. This is the “raw” implementation of the SSE standard. StreamedResponse keep an HTTP connection open Create a new controller. We will use a generator or a loop to simulate streaming data. namespace App\Controller; use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; use Symfony\Component\HttpFoundation\StreamedResponse; use Symfony\Component\Routing\Attribute\Route; #[Route('/api/stream', name: 'api_stream_stock')] class StockStreamController extends AbstractController { #[Route('/stock/{symbol}', name: 'stock_ticker', methods: ['GET'])] public function stream(string $symbol): StreamedResponse { // 1. Create the StreamedResponse $response = new StreamedResponse(function () use ($symbol) { // 2. Prevent PHP time limits for long-running processes set_time_limit(0); // 3. Simple loop to simulate data stream // In a real app, you might check Redis or a Database here $i = 0; while (true) { // Connection check: Stop if client disconnected if (connection_aborted()) { break; } $data = [ 'symbol' => strtoupper($symbol), 'price' => rand(100, 200), 'timestamp' => date('c'), 'sequence' => $i++ ]; // 4. Format according to SSE Spec // Format: "data: {payload}\n\n" echo "event: stock_update\n"; // Optional event name echo 'data: ' . json_encode($data) . "\n\n"; // 5. Critical: Flush the buffer to send data immediately ob_flush(); flush(); // simulate delay sleep(2); } }); // 6. Set Headers specifically for SSE $response->headers->set('Content-Type', 'text/event-stream'); $response->headers->set('Cache-Control', 'no-cache'); $response->headers->set('X-Accel-Buffering', 'no'); // Crucial for Nginx return $response; } } namespace App\Controller; use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; use Symfony\Component\HttpFoundation\StreamedResponse; use Symfony\Component\Routing\Attribute\Route; #[Route('/api/stream', name: 'api_stream_stock')] class StockStreamController extends AbstractController { #[Route('/stock/{symbol}', name: 'stock_ticker', methods: ['GET'])] public function stream(string $symbol): StreamedResponse { // 1. Create the StreamedResponse $response = new StreamedResponse(function () use ($symbol) { // 2. Prevent PHP time limits for long-running processes set_time_limit(0); // 3. Simple loop to simulate data stream // In a real app, you might check Redis or a Database here $i = 0; while (true) { // Connection check: Stop if client disconnected if (connection_aborted()) { break; } $data = [ 'symbol' => strtoupper($symbol), 'price' => rand(100, 200), 'timestamp' => date('c'), 'sequence' => $i++ ]; // 4. Format according to SSE Spec // Format: "data: {payload}\n\n" echo "event: stock_update\n"; // Optional event name echo 'data: ' . json_encode($data) . "\n\n"; // 5. Critical: Flush the buffer to send data immediately ob_flush(); flush(); // simulate delay sleep(2); } }); // 6. Set Headers specifically for SSE $response->headers->set('Content-Type', 'text/event-stream'); $response->headers->set('Cache-Control', 'no-cache'); $response->headers->set('X-Accel-Buffering', 'no'); // Crucial for Nginx return $response; } } You do not need a library for this. The browser’s native EventSource is robust. Symfony SSE Stream Live Ticker: LOADING... -- const symbol = 'AAPL'; // Connect to the Symfony endpoint const eventSource = new EventSource(`/api/stream/stock/${symbol}`); // Listen for the specific 'stock_update' event name defined in PHP eventSource.addEventListener('stock_update', (e) => { const data = JSON.parse(e.data); document.getElementById('symbol').innerText = data.symbol; document.getElementById('price').innerText = '$' + data.price; // Log for visibility const li = document.createElement('li'); li.innerText = `${data.timestamp}: $${data.price}`; document.getElementById('log').prepend(li); }); eventSource.onerror = (err) => { console.error("EventSource failed:", err); // EventSource auto-reconnects by default, but you can handle closure here }; Symfony SSE Stream Live Ticker: LOADING... -- const symbol = 'AAPL'; // Connect to the Symfony endpoint const eventSource = new EventSource(`/api/stream/stock/${symbol}`); // Listen for the specific 'stock_update' event name defined in PHP eventSource.addEventListener('stock_update', (e) => { const data = JSON.parse(e.data); document.getElementById('symbol').innerText = data.symbol; document.getElementById('price').innerText = '$' + data.price; // Log for visibility const li = document.createElement('li'); li.innerText = `${data.timestamp}: $${data.price}`; document.getElementById('log').prepend(li); }); eventSource.onerror = (err) => { console.error("EventSource failed:", err); // EventSource auto-reconnects by default, but you can handle closure here }; Server Configuration (Critical) This is where most developers fail. Web servers (nginx, etc.) love to buffer output to optimize compression. For SSE, buffering kills the stream (the client receives nothing until the buffer fills). You must disable fastcgi_buffering or use the X-Accel-Buffering: no header we added in the controller. fastcgi_buffering X-Accel-Buffering: no header # inside your location ~ \.php$ block fastcgi_split_path_info ^(.+\.php)(/.+)$; # ... standard config ... # Ensure buffering is off for SSE if headers fail fastcgi_buffering off; # inside your location ~ \.php$ block fastcgi_split_path_info ^(.+\.php)(/.+)$; # ... standard config ... # Ensure buffering is off for SSE if headers fail fastcgi_buffering off; Check your php.ini. Ensure output_buffering is set to Off or a low value. php.ini output_buffering Off Verification: Start your local server: symfony server:start Open your terminal. Use curl to verify the stream without a browser: Start your local server: symfony server:start Start your local server: symfony server:start symfony server:start Open your terminal. Open your terminal. Use curl to verify the stream without a browser: Use curl to verify the stream without a browser: curl curl -N -v http://127.0.0.1:8000/api/stream/stock/AAPL curl -N -v http://127.0.0.1:8000/api/stream/stock/AAPL -N: Disables buffering in curl. Expected Output: You should see one JSON object appear every 2 seconds. -N: Disables buffering in curl. -N: Expected Output: You should see one JSON object appear every 2 seconds. Expected Output: The “Senior” Reality Check (Why Native is Dangerous) While the code above works, I rarely recommend it for high-traffic production apps. PHP is synchronous. When a client connects to /api/stream/stock/AAPL, that PHP-FPM worker process enters a while(true) loop. It is locked. PHP is synchronous while(true) loop It is locked If you have 50 PHP-FPM workers and 50 users open this page, your entire site goes down. No other requests can be processed. It also keeps a database connection open if you aren’t careful. You have to offload the open connection management to a dedicated service specifically designed for it. In the Symfony ecosystem, that solution is Mercure. Mercure The Production Approach (Mercure) Mercure is an open protocol for real-time updates. It acts as a Hub. Client connects to the Hub (not your PHP app) to listen for events. Symfony sends a single POST request to the Hub when data changes. Hub broadcasts the data to thousands of listeners. Result: Zero blocking PHP processes. Client connects to the Hub (not your PHP app) to listen for events. Symfony sends a single POST request to the Hub when data changes. Hub broadcasts the data to thousands of listeners. Result: Zero blocking PHP processes. In the production environment, you cannot leave your stream public. You need to control who can listen to what. Mercure uses JSON Web Tokens (JWT) for this. JSON Web Tokens (JWT) Publisher JWT: Allows your Symfony app to push data (handled automatically by the bundle via MERCURE_JWT_SECRET). Subscriber JWT: Allows a user’s browser to listen to private updates. Publisher JWT: Allows your Symfony app to push data (handled automatically by the bundle via MERCURE_JWT_SECRET). Publisher JWT: MERCURE_JWT_SECRET Subscriber JWT: Allows a user’s browser to listen to private updates. Subscriber JWT: Here is how to implement the Subscriber JWT flow in Symfony 7.4. Subscriber JWT Install JWT Library We need a library to generate tokens manually for our users. lcobucci/jwt is the standard in the PHP ecosystem. lcobucci/jwt composer require lcobucci/jwt composer require lcobucci/jwt The Token Generator Service Create a service that generates a signed JWT for a specific user. This token will contain a mercure claim listing the topics the user is allowed to access. mercure //src/Service/MercureTokenGenerator.php namespace App\Service; use Lcobucci\JWT\Configuration; use Lcobucci\JWT\Signer\Hmac\Sha256; use Lcobucci\JWT\Signer\Key\InMemory; use Symfony\Component\DependencyInjection\Attribute\Autowire; class MercureTokenGenerator { private Configuration $config; public function __construct( // Inject the same secret used in your .env for the Mercure Hub #[Autowire('%env(MERCURE_JWT_SECRET)%')] private string $secret ) { $this->config = Configuration::forSymmetricSigner( new Sha256(), InMemory::plainText($this->secret) ); } public function generate(string $userTopic): string { return $this->config->builder() ->withClaim('mercure', [ 'subscribe' => [ $userTopic, // Allow access to this specific topic // 'https://mysite.com/books/{id}' // You can add patterns here ] ]) ->getToken($this->config->signer(), $this->config->signingKey()) ->toString(); } } //src/Service/MercureTokenGenerator.php namespace App\Service; use Lcobucci\JWT\Configuration; use Lcobucci\JWT\Signer\Hmac\Sha256; use Lcobucci\JWT\Signer\Key\InMemory; use Symfony\Component\DependencyInjection\Attribute\Autowire; class MercureTokenGenerator { private Configuration $config; public function __construct( // Inject the same secret used in your .env for the Mercure Hub #[Autowire('%env(MERCURE_JWT_SECRET)%')] private string $secret ) { $this->config = Configuration::forSymmetricSigner( new Sha256(), InMemory::plainText($this->secret) ); } public function generate(string $userTopic): string { return $this->config->builder() ->withClaim('mercure', [ 'subscribe' => [ $userTopic, // Allow access to this specific topic // 'https://mysite.com/books/{id}' // You can add patterns here ] ]) ->getToken($this->config->signer(), $this->config->signingKey()) ->toString(); } } Injecting the Token (The Cookie Method) The native browser EventSource API does not support sending HTTP Headers (like Authorization: Bearer). EventSource API Authorization: Bearer To solve this without adding heavy JavaScript polyfills, we use a Cookie. The Mercure Hub automatically looks for a cookie named mercureAuthorization. Cookie mercureAuthorization //src/Controller/StockPageController.php namespace App\Controller; use App\Service\MercureTokenGenerator; use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; use Symfony\Component\HttpFoundation\Cookie; use Symfony\Component\HttpFoundation\Response; use Symfony\Component\Routing\Attribute\Route; class StockPageController extends AbstractController { #[Route('/dashboard', name: 'app_dashboard')] public function index(MercureTokenGenerator $tokenGenerator): Response { // 1. Define the private topic this user is allowed to see $userTopic = 'https://mysite.com/user/123/alerts'; // 2. Generate the JWT $token = $tokenGenerator->generate($userTopic); // 3. Create the response (render your Twig template) $response = $this->render('dashboard/index.html.twig', [ 'userTopic' => $userTopic ]); // 4. Attach the JWT as a Cookie // The Hub must be on the same domain (or subdomain) for this to work $response->headers->setCookie(Cookie::create( 'mercureAuthorization', $token, 0, // Session cookie '/.well-known/mercure', // Path (critical: restricts cookie to Hub) null, // Domain (null = current domain) false, // Secure (true if HTTPS) true, // HttpOnly false, // Raw 'strict' // SameSite )); return $response; } } //src/Controller/StockPageController.php namespace App\Controller; use App\Service\MercureTokenGenerator; use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; use Symfony\Component\HttpFoundation\Cookie; use Symfony\Component\HttpFoundation\Response; use Symfony\Component\Routing\Attribute\Route; class StockPageController extends AbstractController { #[Route('/dashboard', name: 'app_dashboard')] public function index(MercureTokenGenerator $tokenGenerator): Response { // 1. Define the private topic this user is allowed to see $userTopic = 'https://mysite.com/user/123/alerts'; // 2. Generate the JWT $token = $tokenGenerator->generate($userTopic); // 3. Create the response (render your Twig template) $response = $this->render('dashboard/index.html.twig', [ 'userTopic' => $userTopic ]); // 4. Attach the JWT as a Cookie // The Hub must be on the same domain (or subdomain) for this to work $response->headers->setCookie(Cookie::create( 'mercureAuthorization', $token, 0, // Session cookie '/.well-known/mercure', // Path (critical: restricts cookie to Hub) null, // Domain (null = current domain) false, // Secure (true if HTTPS) true, // HttpOnly false, // Raw 'strict' // SameSite )); return $response; } } Updating the Publisher Now, update your publisher service to mark the update as Private. // ... public function publishPrivateAlert(string $userId, string $message): void { $topic = "https://mysite.com/user/{$userId}/alerts"; $update = new Update( $topic, json_encode(['alert' => $message]), true // hub->publish($update); } // ... public function publishPrivateAlert(string $userId, string $message): void { $topic = "https://mysite.com/user/{$userId}/alerts"; $update = new Update( $topic, json_encode(['alert' => $message]), true // hub->publish($update); } Client Side (No Changes Needed) Because we used a Cookie, the JavaScript remains exactly the same. The browser will automatically send the mercureAuthorization cookie when it connects to the Hub. Cookie mercureAuthorization // The browser sends the cookie automatically! const eventSource = new EventSource(hubUrl); // The browser sends the cookie automatically! const eventSource = new EventSource(hubUrl); Verification Clear Cookies: Clear your browser cookies for localhost. Load Dashboard: Visit /dashboard. Inspect the Network tab. You should see a Set-Cookie header with mercureAuthorization. Check Connection: The EventSource request to the Hub should now be green (200 OK). Test Privacy: Try to curl the Hub directly without the cookie; you will receive a 401 Unauthorized for private topics. Clear Cookies: Clear your browser cookies for localhost. Clear Cookies: Load Dashboard: Visit /dashboard. Inspect the Network tab. You should see a Set-Cookie header with mercureAuthorization. Load Dashboard: /dashboard Set-Cookie mercureAuthorization Check Connection: The EventSource request to the Hub should now be green (200 OK). Check Connection: Test Privacy: Try to curl the Hub directly without the cookie; you will receive a 401 Unauthorized for private topics. Test Privacy: curl 401 Unauthorized Conclusion As we have explored, implementing real-time data in Symfony 7.4 isn’t just about opening a connection; it is about choosing the architecture that matches your traffic patterns. While the Native StreamedResponse offers a quick, dependency-free route for administrative tasks (like export progress bars) or low-traffic internal tools, it carries significant risks regarding PHP worker exhaustion. It is a synchronous solution in an asynchronous world. Native StreamedResponse For any user-facing feature — whether it’s a live dashboard, a notification center, or a collaborative tool — Mercure is the non-negotiable standard for the modern Symfony ecosystem. It completely decouples your application logic from the connection management, allowing your Symfony backend to remain stateless and performant while Caddy handles the heavy lifting of maintaining thousands of idle connections. Mercure non-negotiable standard modern Symfony ecosystem Mastering these patterns allows you to move beyond simple “request-response” lifecycles and build applications that feel alive and responsive. Let’s Stay in Touch Real-time architecture often brings hidden complexities regarding load balancing, reverse proxy configuration (Nginx/HAProxy), and security boundaries. Let’s discuss how we can make your application real-time ready.