PHPackages                             valksor/php-sse - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. valksor/php-sse

ActiveLibrary[Utility & Helpers](/categories/utility)

valksor/php-sse
===============

Server-Sent Events implementation for real-time communication with process management and Symfony integration

014PHPCI passing

Since Jan 23Pushed 3mo agoCompare

[ Source](https://github.com/valksor/php-sse)[ Packagist](https://packagist.org/packages/valksor/php-sse)[ RSS](/packages/valksor-php-sse/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

Valksor Component: SSE
======================

[](#valksor-component-sse)

[![valksor](https://camo.githubusercontent.com/2af5a6a7e5f7da47cd0a924c8b00038f208f45f9b0d5be8d7a497a9808168187/68747470733a2f2f62616467656e2e6e65742f7374617469632f6f72672f76616c6b736f722f677265656e)](https://github.com/valksor)[![BSD-3-Clause](https://camo.githubusercontent.com/72547f8afb6b5ace804caebbf95c3bcbfc027ce9214777bc452f308f3165db01/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4253442d2d332d2d436c617573652d677265656e3f7374796c653d666c6174)](https://github.com/valksor/php-sse/blob/master/LICENSE)[![Coverage Status](https://camo.githubusercontent.com/1fcd005ab0c08bed714dc67e213304dcc17e7a0d042d3f0d5081a209daed867b/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f76616c6b736f722f7068702d7373652f62616467652e7376673f6272616e63683d6d6173746572)](https://coveralls.io/github/valksor/php-sse?branch=master)[![php](https://camo.githubusercontent.com/77da2f7bbc049873edb2d1045a756d7a32e3ba50440a8e0e76a9109f62f0771b/68747470733a2f2f62616467656e2e6e65742f7374617469632f7068702f2533453d382e342f707572706c65)](https://www.php.net/releases/8.4/en.php)

A Server-Sent Events (SSE) component that provides real-time, unidirectional communication from server to client, enabling live updates, programmatic reloads, and dynamic content streaming in Symfony applications.

Features
--------

[](#features)

- **Real-time Server-Sent Events**: Bidirectional SSE server with process management
- **Programmatic Reloads**: Automatic browser reloads during development
- **Import Map Integration**: Dynamic JavaScript module loading with modern import maps
- **Twig Integration**: Custom Twig functions for SSE and import map management
- **Process Management**: Automatic process cleanup and conflict resolution
- **Asset Mapper Support**: Integration with Symfony's asset mapper system
- **Signal Handling**: Proper signal handling for graceful shutdown

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require valksor/php-sse
```

Requirements
------------

[](#requirements)

- PHP 8.4 or higher
- JSON extension
- PCNTL extension (for process management)
- POSIX extension
- Symfony Framework
- Twig templating engine
- Valksor Bundle (for automatic configuration)
- AssetMapper integration (automatic)

Usage
-----

[](#usage)

### Basic Setup

[](#basic-setup)

1. Register the bundle in your Symfony application:

```
// config/bundles.php
return [
    // ...
    Valksor\Bundle\ValksorBundle::class => ['all' => true],
    // ...
];
```

2. Enable the SSE component:

```
# config/packages/valksor.yaml
valksor:
    sse:
        enabled: true
        port: 8080 # SSE server port
        host: localhost # SSE server host
        ping_interval: 30 # Ping interval in seconds
```

3. Set up asset mapping:

Copy the importmap.php.example file from the SSE component to your project root:

```
# Copy from the SSE component Resources directory
cp src/valksor/src/Valksor/Component/Sse/Resources/importmap.php.example importmap.php
```

The configuration automatically detects your environment and includes SSE assets from:

- Local development (`valksor/` directory)
- FullStack package (`vendor/valksor/valksor/`)
- Standalone SSE package (`vendor/valksor/php-sse/`)

4. Add SSE to your template:

```
{# In your base layout template #}
{% block javascripts %}
    {{ include('@ValksorSse/sse.html.twig') }}
{% endblock %}
```

### Development Server

[](#development-server)

Start the SSE server for development:

```
# Start the SSE server
php bin/console valksor:sse

# Or run in the background
php bin/console valksor:sse &
```

The server will:

- Start an SSE server on the configured host and port
- Handle client connections and send real-time events
- Provide automatic browser reload functionality
- Manage process lifecycle and cleanup

### Integration with Valksor Dev Tools

[](#integration-with-valksor-dev-tools)

The SSE component is automatically integrated with the new Valksor build system architecture:

#### Automatic SSE Integration with Development Commands

[](#automatic-sse-integration-with-development-commands)

When using the new 3-command architecture:

```
# Lightweight development (includes SSE + hot reload)
php bin/console valksor:dev

# Full development environment (includes SSE + all services)
php bin/console valksor:watch
```

Both commands automatically start the SSE server as part of the `hot_reload` provider, so you don't need to run `valksor:sse` separately during development.

#### Build System Integration

[](#build-system-integration)

The SSE component works seamlessly with the service registry architecture:

- **Provider Integration**: SSE functionality is provided by the `HotReloadProvider`
- **Flag-Based Execution**: Automatically runs with commands that use the `dev` flag
- **Process Management**: SSE processes are managed by the build system's process manager
- **Dependency Resolution**: SSE server starts before file watching begins

#### Configuration Integration

[](#configuration-integration)

The SSE component can be used independently or integrated with other systems:

```
# config/packages/valksor.yaml - SSE-only configuration
valksor:
    sse:
        enabled: true
        port: 8080
        host: localhost
        ping_interval: 30
```

For build system integration examples, see the ValksorDev Build Tools documentation.

#### When to Use Standalone SSE vs Build System Integration

[](#when-to-use-standalone-sse-vs-build-system-integration)

**Use Build System Integration (`valksor:dev`/`valksor:watch`):**

- Development environment with hot reload
- Multiple services need to run together
- Automatic process management required
- File watching + SSE functionality needed

**Use Standalone SSE (`valksor:sse`):**

- Production SSE server deployment
- Custom SSE-only applications
- Integration with other build systems
- Manual process control preferred

### Asset Setup

[](#asset-setup)

The SSE component requires an importmap.php configuration in your project root that automatically detects and includes the SSE assets.

Copy the importmap.php.example file from the SSE component to your project root:

```
# Copy from the SSE component Resources directory
cp src/valksor/src/Valksor/Component/Sse/Resources/importmap.php.example importmap.php
```

The configuration automatically detects your environment and includes SSE assets from:

- Local development (`valksor/` directory)
- FullStack package (`vendor/valksor/valksor/`)
- Standalone SSE package (`vendor/valksor/php-sse/`)

### Twig Integration

[](#twig-integration)

The component provides SSE integration through a simple template include:

```
{# Add the SSE template include to your layout #}
{% block javascripts %}
    {{ include('@ValksorSse/sse.html.twig') }}
{% endblock %}
```

The SSE template automatically handles:

- Server connection detection via `valksor_sse_ping()`
- Meta tag injection for SSE configuration (`valksor-sse-port`, `valksor-sse-path`)
- JavaScript client loading via `valksor_sse_importmap_scripts(['valksorsse/sse'])`

For advanced usage, you can also use the individual Twig functions:

```
{# Manual import map definition #}
{{ valksor_sse_importmap_definition(['your-assets']) }}

{# Manual script loading #}
{{ valksor_sse_importmap_scripts(['your-assets']) }}

{# Connection testing #}
{% if valksor_sse_ping() %}

{% endif %}
```

### Frontend JavaScript Usage

[](#frontend-javascript-usage)

Once the SSE scripts are loaded, you can use the client-side API:

```
// The SSE client is automatically initialized
// Listen for reload events
window.addEventListener("sse:reload", () => {
    console.log("Page will reload...");
});

// Custom event handling
const sseClient = window.sseClient;

// Listen for custom events
sseClient.addEventListener("custom-event", (event) => {
    console.log("Custom event:", event.data);
});

// Send ping messages
sseClient.ping();

// Check connection status
if (sseClient.isConnected()) {
    console.log("SSE connection is active");
}
```

### Advanced Configuration

[](#advanced-configuration)

#### Complete Configuration Example

[](#complete-configuration-example)

```
# config/packages/valksor.yaml
valksor:
    sse:
        enabled: true
        host: localhost
        port: 8080
        ping_interval: 30
        max_connections: 100
        timeout: 300
        debug: false
```

#### Custom Event Broadcasting

[](#custom-event-broadcasting)

Create custom services to broadcast events:

```