webware/sse

A PHP library for Server-Sent Events (SSE) that provides a simple and efficient way to send real-time updates from the server to the client.

0.1.x-dev 2026-03-15 02:16 UTC

Requires

• php: ~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0
• laminas/laminas-diactoros: ^3.0
• laminas/laminas-httphandlerrunner: ^2.0
• psr/container: ^2.0
• psr/http-message: ^2.0
• psr/http-server-handler: ^1.0
• psr/http-server-middleware: ^1.0

Requires (Dev)

• laminas/laminas-servicemanager: ^4.0
• phpstan/phpstan: ^2.1
• phpstan/phpstan-phpunit: ^2.0
• phpunit/phpunit: ^11.5.42
• roave/security-advisories: dev-master
• webware/coding-standard: ^0.1.0

Suggests

• laminas/laminas-servicemanager: Provides ServiceManager integration for Mezzio applications; required to use the bundled ConfigProvider with laminas-servicemanager-based containers

BSD-3-Clause

• Joey (aka Tyrsson) Smith

• php
• sse
• Server-Sent Events

README

A Server-Sent Events (SSE) component for Mezzio applications built on the Laminas ecosystem.

• PSR-7 native — SseResponse extends Laminas\Diactoros\Response
• EmitterStack-aware — SseEmitter implements EmitterInterface and returns false for non-SSE responses, letting SapiEmitter handle the rest
• PSR-15 ready — abstract handler base class and dual-mode middleware
• Generator-based — yield events directly from PHP generators for clean, lazy streaming
• Reconnection support — Last-Event-ID header extracted and forwarded automatically
• Built-in heartbeat — configurable keep-alive comment frames
• PSR-11 container — ConfigProvider registers services with any PSR-11 container; laminas-servicemanager is optional

Quick Start

1. Install

composer require webware/sse

2. Register the ConfigProvider

// config/config.php
use Laminas\ConfigAggregator\ConfigAggregator;
use Webware\SSE\ConfigProvider;

$aggregator = new ConfigAggregator([
    ConfigProvider::class,
    // your other providers …
]);

3. Push SseEmitter onto the EmitterStack

// public/index.php (or wherever your Mezzio bootstrap lives)
use Laminas\HttpHandlerRunner\Emitter\EmitterStack;
use Laminas\HttpHandlerRunner\Emitter\SapiEmitter;
use Webware\SSE\SseEmitter;

$stack = new EmitterStack();
$stack->push(new SapiEmitter());                    // handles regular responses
$stack->push($container->get(SseEmitter::class));   // handles SseResponse first

4. Create an event handler

use Generator;
use Psr\Http\Message\ServerRequestInterface;
use Webware\SSE\AbstractSseHandler;
use Webware\SSE\Event;

final class TimeHandler extends AbstractSseHandler
{
    protected function stream(
        ServerRequestInterface $request,
        ?string $lastEventId,
    ): Generator {
        while (true) {
            yield new Event(data: date('H:i:s'), event: 'tick');
            sleep(1);
            yield null; // trigger heartbeat check between real events
        }
    }
}

5. Route it

// config/routes.php
$app->get('/events/time', TimeHandler::class);

6. Subscribe in the browser

<!-- ESM (modern browsers / bundlers) -->
<script type="module">
  import { SseClient } from './js/sse-client.js';

  const client = new SseClient('/events/time', {
    onOpen:  () => console.log('connected'),
    onError: (err) => console.warn('error', err),
  });

  client.on('tick', (time) => console.log('server time:', time));
</script>

<!-- Or via the IIFE global build -->
<script src="js/sse-client.iife.js"></script>
<script>
  const client = new SseClient('/events/time');
  client.on('tick', (time) => console.log('server time:', time));
</script>

Documentation

Topic	Description
Installation	Requirements, Composer install, optional packages
Configuration	ConfigProvider, webware_sse config keys, overriding defaults
Events	Event, EventInterface, named events, multi-line data, retry
SseResponse	PSR-7 response object, default headers, custom headers
SseEmitter	EmitterStack setup, heartbeat, connection abort handling
AbstractSseHandler	PSR-15 handler base class, Last-Event-ID, reconnection
SseMiddleware	Preprocessor mode, terminal factory mode
Mezzio Integration	Full end-to-end guide for Mezzio applications
JavaScript Client	Browser / Node SSE client with reconnect, typed events, and polyfill

Requirements

• PHP 8.2, 8.3, 8.4, or 8.5
• laminas/laminas-diactoros ^3.0
• laminas/laminas-httphandlerrunner ^2.0

License

BSD-3-Clause. See LICENSE.