feature symfony#58743 [HttpFoundation] Streamlining server event streaming (yceruto)

This PR was merged into the 7.3 branch.

Discussion
----------

[HttpFoundation] Streamlining server event streaming

| Q             | A
| ------------- | ---
| Branch?       | 7.3
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Issues        | -
| License       | MIT

While [Mercure](https://mercure.rocks/) is the recommended option for most cases, implementing a custom Server-sent Event (SSE) backend relying on Symfony components is still a good alternative.

Example using today’s code:
```php
public function __invoke(): StreamedResponse
{
    $response = new StreamedResponse(function () {
        foreach ($this->watchJobsInProgress() as $job) {
            echo "type: jobs\n";
            echo "data: ".$job->toJson()."\n\n";

            StreamedResponse::closeOutputBuffers(0, true);
            flush();

            if (connection_aborted()) {
                break;
            }

            sleep(1);
        }
    });
    $response->headers->set('Content-Type', 'text/event-stream');
    $response->headers->set('Cache-Control', 'no-cache');
    $response->headers->set('Connection', 'keep-alive');
    $response->headers->set('X-Accel-Buffering', 'no');

    return $response;
}
```

So, this PR simplifies that implementation by adding two new artifacts:

### ✨ New `ServerEvent` DTO class

Spec: https://html.spec.whatwg.org/multipage/server-sent-events.html

The `ServerEvent` class represents individual events streamed from the server to clients. It includes fields like `data`, `type`, `id`, `retry`, and `comment`, so it can cover a variety of use cases.

One key feature is the `__toString()` method, which automatically serializes all these fields into the proper SSE format. This saves us from having to manually format the events, making the process a lot smoother. Plus, it supports iterable `data`, meaning it can handle multi-line messages or more complex data structures all in one event.

### ✨ New `EventStreamResponse` class

* **Simplified Headers Setup**

  ```php
  return new EventStreamResponse(/* ... */);
  ```
  This class automatically sets the required headers (`Content-Type`, `Cache-Control`, and `Connection`), ensuring that every response is properly configured for event streaming without additional code.

* **Generator-based Event Streaming with Auto Flush**

  ```php
  return new EventStreamResponse(function (): \Generator {
      yield new ServerEvent(time(), type: 'ping');
  });
  ```
  The callback function can now `yield` events directly, automatically handling serialization and output buffering as each new event occurs.

* **Event Streaming with Sending Control**

  ```php
  return new EventStreamResponse(function (EventStreamResponse $response) {
      $response->sendEvent(new ServerEvent('...'));
      // do something in between ...
      $response->sendEvent(new ServerEvent('...'));
  });
  ```
  The callback function receives a new argument—the response instance—allowing you to manually `sendEvent()`.

  This method is especially useful when `yield` is not possible due to scope limitations. In the example below, the callback handles the event inside an event stream response, listening for Redis messages and directly triggering the `sendEvent()` method:
  ```php
  return new EventStreamResponse(function (EventStreamResponse $response) {
      $redis = new \Redis();
      $redis->connect('127.0.0.1');
      $redis->subscribe(['message'], function (/* ... */, string $message) use ($response) {
          $response->sendEvent(new ServerEvent($message));
      });
  });
  ```

* **Retry Event Fallback**

  ```php
  return new EventStreamResponse(/* ... */, retry: 1000);
  ```
  `ServerEvent` allows setting individual `retry` intervals, which take precedence over the default retry configured in `EventStreamResponse`. If not specified at the event level, the global retry setting applies.

This is the final, optimized version after the proposed improvements:
```php
public function __invoke(): EventStreamResponse
{
    return new EventStreamResponse(function () {
        foreach ($this->watchJobsInProgress() as $job) {
            yield new ServerEvent($job->toJson(), type: 'jobs');

            sleep(1);
        }
    });
}
```
Cheers!

Commits
-------

0bfd3d3 Streamlining server event streaming

Author: fabpot

src/Symfony/Component/HttpFoundation/CHANGELOG.md

@@ -5,6 +5,7 @@ CHANGELOG
 ---
 
  * Add support for iterable of string in `StreamedResponse`
+ * Add `EventStreamResponse` and `ServerEvent` classes to streamline server event streaming
 
 7.2
 ---

src/Symfony/Component/HttpFoundation/EventStreamResponse.php

@@ -0,0 +1,110 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\HttpFoundation;
+
+/**
+ * Represents a streaming HTTP response for sending server events
+ * as part of the Server-Sent Events (SSE) streaming technique.
+ *
+ * To broadcast events to multiple users at once, for long-running
+ * connections and for high-traffic websites, prefer using the Mercure
+ * Symfony Component, which relies on Software designed for these use
+ * cases: https://symfony.com/doc/current/mercure.html
+ *
+ * @see ServerEvent
+ *
+ * @author Yonel Ceruto <open@yceruto.dev>
+ *
+ * Example usage:
+ *
+ *     return new EventStreamResponse(function () {
+ *         yield new ServerEvent(time());
+ *
+ *         sleep(1);
+ *
+ *         yield new ServerEvent(time());
+ *     });
+ */
+class EventStreamResponse extends StreamedResponse
+{
+    /**
+     * @param int|null $retry The number of milliseconds the client should wait
+     *                        before reconnecting in case of network failure
+     */
+    public function __construct(?callable $callback = null, int $status = 200, array $headers = [], private ?int $retry = null)
+    {
+        $headers += [
+            'Connection' => 'keep-alive',
+            'Content-Type' => 'text/event-stream',
+            'Cache-Control' => 'private, no-cache, no-store, must-revalidate, max-age=0',
+            'X-Accel-Buffering' => 'no',
+            'Pragma' => 'no-cache',
+            'Expire' => '0',
+        ];
+
+        parent::__construct($callback, $status, $headers);
+    }
+
+    public function setCallback(callable $callback): static
+    {
+        if ($this->callback) {
+            return parent::setCallback($callback);
+        }
+
+        $this->callback = function () use ($callback) {
+            if (is_iterable($events = $callback($this))) {
+                foreach ($events as $event) {
+                    $this->sendEvent($event);
+
+                    if (connection_aborted()) {
+                        break;
+                    }
+                }
+            }
+        };
+
+        return $this;
+    }
+
+    /**
+     * Sends a server event to the client.
+     *
+     * @return $this
+     */
+    public function sendEvent(ServerEvent $event): static
+    {
+        if ($this->retry > 0 && !$event->getRetry()) {
+            $event->setRetry($this->retry);
+        }
+
+        foreach ($event as $part) {
+            echo $part;
+
+            if (!\in_array(\PHP_SAPI, ['cli', 'phpdbg', 'embed'], true)) {
+                static::closeOutputBuffers(0, true);
+                flush();
+            }
+        }
+
+        return $this;
+    }
+
+    public function getRetry(): ?int
+    {
+        return $this->retry;
+    }
+
+    public function setRetry(int $retry): void
+    {
+        $this->retry = $retry;
+    }
+}

src/Symfony/Component/HttpFoundation/ServerEvent.php

@@ -0,0 +1,147 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\HttpFoundation;
+
+/**
+ * An event generated on the server intended for streaming to the client
+ * as part of the SSE streaming technique.
+ *
+ * @implements \IteratorAggregate<string>
+ *
+ * @author Yonel Ceruto <open@yceruto.dev>
+ */
+class ServerEvent implements \IteratorAggregate
+{
+    /**
+     * @param string|iterable<string> $data    The event data field for the message
+     * @param string|null             $type    The event type
+     * @param int|null                $retry   The number of milliseconds the client should wait
+     *                                         before reconnecting in case of network failure
+     * @param string|null             $id      The event ID to set the EventSource object's last event ID value
+     * @param string|null             $comment The event comment
+     */
+    public function __construct(
+        private string|iterable $data,
+        private ?string $type = null,
+        private ?int $retry = null,
+        private ?string $id = null,
+        private ?string $comment = null,
+    ) {
+    }
+
+    public function getData(): iterable|string
+    {
+        return $this->data;
+    }
+
+    /**
+     * @return $this
+     */
+    public function setData(iterable|string $data): static
+    {
+        $this->data = $data;
+
+        return $this;
+    }
+
+    public function getType(): ?string
+    {
+        return $this->type;
+    }
+
+    /**
+     * @return $this
+     */
+    public function setType(string $type): static
+    {
+        $this->type = $type;
+
+        return $this;
+    }
+
+    public function getRetry(): ?int
+    {
+        return $this->retry;
+    }
+
+    /**
+     * @return $this
+     */
+    public function setRetry(?int $retry): static
+    {
+        $this->retry = $retry;
+
+        return $this;
+    }
+
+    public function getId(): ?string
+    {
+        return $this->id;
+    }
+
+    /**
+     * @return $this
+     */
+    public function setId(string $id): static
+    {
+        $this->id = $id;
+
+        return $this;
+    }
+
+    public function getComment(): ?string
+    {
+        return $this->comment;
+    }
+
+    public function setComment(string $comment): static
+    {
+        $this->comment = $comment;
+
+        return $this;
+    }
+
+    /**
+     * @return \Traversable<string>
+     */
+    public function getIterator(): \Traversable
+    {
+        static $lastRetry = null;
+
+        $head = '';
+        if ($this->comment) {
+            $head .= \sprintf(': %s', $this->comment)."\n";
+        }
+        if ($this->id) {
+            $head .= \sprintf('id: %s', $this->id)."\n";
+        }
+        if ($this->retry > 0 && $this->retry !== $lastRetry) {
+            $head .= \sprintf('retry: %s', $lastRetry = $this->retry)."\n";
+        }
+        if ($this->type) {
+            $head .= \sprintf('event: %s', $this->type)."\n";
+        }
+        yield $head;
+
+        if ($this->data) {
+            if (is_iterable($this->data)) {
+                foreach ($this->data as $data) {
+                    yield \sprintf('data: %s', $data)."\n";
+                }
+            } else {
+                yield \sprintf('data: %s', $this->data)."\n";
+            }
+        }
+
+        yield "\n";
+    }
+}

src/Symfony/Component/HttpFoundation/Tests/EventStreamResponseTest.php

@@ -0,0 +1,127 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\HttpFoundation\Tests;
+
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\HttpFoundation\EventStreamResponse;
+use Symfony\Component\HttpFoundation\ServerEvent;
+
+class EventStreamResponseTest extends TestCase
+{
+    public function testInitializationWithDefaultValues()
+    {
+        $response = new EventStreamResponse();
+
+        $this->assertSame('text/event-stream', $response->headers->get('content-type'));
+        $this->assertSame('max-age=0, must-revalidate, no-cache, no-store, private', $response->headers->get('cache-control'));
+        $this->assertSame('keep-alive', $response->headers->get('connection'));
+
+        $this->assertSame(200, $response->getStatusCode());
+        $this->assertNull($response->getRetry());
+    }
+
+    public function testStreamSingleEvent()
+    {
+        $response = new EventStreamResponse(function () {
+            yield new ServerEvent(
+                data: 'foo',
+                type: 'bar',
+                retry: 100,
+                id: '1',
+                comment: 'bla bla',
+            );
+        });
+
+        $expected = <<<STR
+: bla bla
+id: 1
+retry: 100
+event: bar
+data: foo
+
+
+STR;
+
+        $this->assertSameResponseContent($expected, $response);
+    }
+
+    public function testStreamEventsAndData()
+    {
+        $data = static function (): iterable {
+            yield 'first line';
+            yield 'second line';
+            yield 'third line';
+        };
+
+        $response = new EventStreamResponse(function () use ($data) {
+            yield new ServerEvent('single line');
+            yield new ServerEvent(['first line', 'second line']);
+            yield new ServerEvent($data());
+        });
+
+        $expected = <<<STR
+data: single line
+
+data: first line
+data: second line
+
+data: first line
+data: second line
+data: third line
+
+
+STR;
+
+        $this->assertSameResponseContent($expected, $response);
+    }
+
+    public function testStreamEventsWithRetryFallback()
+    {
+        $response = new EventStreamResponse(function () {
+            yield new ServerEvent('foo');
+            yield new ServerEvent('bar');
+            yield new ServerEvent('baz', retry: 1000);
+        }, retry: 1500);
+
+        $expected = <<<STR
+retry: 1500
+data: foo
+
+data: bar
+
+retry: 1000
+data: baz
+
+
+STR;
+
+        $this->assertSameResponseContent($expected, $response);
+    }
+
+    public function testStreamEventWithSendMethod()
+    {
+        $response = new EventStreamResponse(function (EventStreamResponse $response) {
+            $response->sendEvent(new ServerEvent('foo'));
+        });
+
+        $this->assertSameResponseContent("data: foo\n\n", $response);
+    }
+
+    private function assertSameResponseContent(string $expected, EventStreamResponse $response): void
+    {
+        ob_start();
+        $response->send();
+        $actual = ob_get_clean();
+
+        $this->assertSame($expected, $actual);
+    }
+}