Consume Server-Sent Events (SSE) with PHP.
- WHATWG Compliant - Implements the Server-Sent Events specification.
- Memory Efficient - Generator-based event iteration for low memory usage.
- PHP 8.2 or higher.
Install via Composer:
composer require hosmelq/sse
<?php
use HosmelQ\SSE\Client;
$client = new Client();
$eventSource = $client->get('https://example.com/events');
foreach ($eventSource->events() as $event) {
echo "Data: {$event->data}\n";
echo "Event: {$event->event}\n";
echo "ID: {$event->id}\n";
}
The Client
class is the main entry point for connecting to SSE endpoints:
use HosmelQ\SSE\Client;
use GuzzleHttp\Client as HttpClient;
// Using a default HTTP client
$client = new Client();
// Using a custom HTTP client
$httpClient = new HttpClient(['timeout' => 30]);
$client = new Client($httpClient);
The client supports both GET and POST methods:
// GET request (most common for SSE)
$eventSource = $client->get('https://api.example.com/stream');
// POST request with data
$eventSource = $client->post('https://api.example.com/stream', [
'json' => ['subscribe' => 'user-123']
]);
// Using generic connect method
$eventSource = $client->connect('GET', 'https://api.example.com/stream', [
'read_timeout' => 30,
'timeout' => 60,
]);
foreach ($eventSource->events() as $event) {
echo $event->data; // Event data
echo $event->event; // Event type (default: "message")
echo $event->id; // Event ID (optional)
echo $event->retry; // Retry interval (optional)
}
Events follow the SSE specification with these fields:
// Example event from server:
// data: {"message": "Hello World", "timestamp": 1640995200}
// event: notification
// id: 123
// retry: 5000
$event = /* ... received event ... */;
echo $event->data; // '{"message": "Hello World", "timestamp": 1640995200}'
echo $event->event; // "notification"
echo $event->id; // "123"
echo $event->retry; // 5000
// Parse JSON data
$notification = $event->json();
echo $notification['message']; // "Hello World"
$eventSource = $client->get('https://api.example.com/stream', [
'headers' => ['Authorization' => 'Bearer token'],
'query' => ['channel' => 'notifications'],
'read_timeout' => 30,
'timeout' => 60,
]);
The library provides a clean exception hierarchy for different types of errors:
SSEException (base class)
├── SSEConnectionException (connection/transport errors)
└── SSEProtocolException (protocol violations)
SSEConnectionException
- Thrown when connection or transport errors occur.
SSEProtocolException
- Thrown when the server violates the SSE protocol.
SSEException
- Base class that catches all SSE-related errors.
<?php
use HosmelQ\SSE\Client;
use HosmelQ\SSE\SSEException;
use HosmelQ\SSE\SSEConnectionException;
use HosmelQ\SSE\SSEProtocolException;
$client = new Client();
try {
$eventSource = $client->get('https://api.example.com/stream');
foreach ($eventSource->events() as $event) {
}
} catch (SSEConnectionException $e) {
echo "Connection failed: " . $e->getMessage();
} catch (SSEProtocolException $e) {
echo "Protocol error: " . $e->getMessage();
} catch (SSEException $e) {
echo "SSE Error: " . $e->getMessage();
}
Track the last received event ID for reconnection scenarios:
$eventSource = $client->get('https://api.example.com/stream');
try {
foreach ($eventSource->events() as $event) {
}
} catch (Exception $e) {
$lastEventId = $eventSource->getLastEventId();
$eventSource = $client->get('https://api.example.com/stream', [
'headers' => ['Last-Event-ID' => $lastEventId]
]);
}
composer test
See CHANGELOG.md for a list of changes.
Based on:
The MIT License (MIT). Please see License File for more information.