Rewords and tweaks

Author: javiereguiluz

http_client.rst

@@ -1146,49 +1146,54 @@ installed in your application::
 Consuming Server-Sent Events
 ----------------------------
 
-This component provides an `EventSource`_ implementation to consume Server-Sent Events.
-Use the :class:`Symfony\\Component\\HttpClient\\EventSourceHttpClient`, open a
-connection to a server with the `text/event-stream` content type and consume the stream::
+.. versionadded:: 5.2
+
+    The feature to consume server-sent events was introduced in Symfony 5.2.
+
+`Server-sent events`_ is an Internet standard used to push data to web pages.
+Its JavaScript API is built around an `EventSource`_ object, which listens to
+the events sent from some URL. The events are a stream of data (served with the
+``text/event-stream`` MIME type) with the following format:
+
+.. code-block:: text
+
+    data: This is the first message.
+
+    data: This is the second message, it
+    data: has two lines.
+
+    data: This is the third message.
+
+Symfony's HTTP client provides an EventSource implementation to consume these
+server-sent events. Use the :class:`Symfony\\Component\\HttpClient\\EventSourceHttpClient`
+to wrap your HTTP client, open a connection to a server that responds with a
+``text/event-stream`` content type and consume the stream as follows::
 
     use Symfony\Component\HttpClient\EventSourceHttpClient;
 
+    // the second optional argument is the reconnection time in seconds (default = 10)
     $client = new EventSourceHttpClient($client, 10);
-    $source = $client->connect('http://localhost:8080/events');
+    $source = $client->connect('https://localhost:8080/events');
     while ($source) {
         foreach ($client->stream($source, 2) as $r => $chunk) {
-            // You should handle these chunks yourself
             if ($chunk->isTimeout()) {
-                dump([
-                    'timeout' => [
-                        'retry' => 1 + count($r->getInfo('previous_info') ?? [])
-                    ],
-                ]);
+                // ...
                 continue;
             }
+
             if ($chunk->isLast()) {
-                dump([
-                    'eof' => [
-                        'retries' => count($r->getInfo('previous_info') ?? [])
-                    ],
-                ]);
-                $source = null;
+                // ...
+
                 return;
             }
 
-            // This is a special ServerSentEvent chunk holding the pushed message
+            // this is a special ServerSentEvent chunk holding the pushed message
             if ($chunk instanceof ServerSentEvent) {
-                dump($chunk);
+                // do something with the server event ...
             }
         }
     }
 
-The default reconnection time is `10` seconds and is given onto the second argument of
-the :class:`Symfony\\Component\\HttpClient\\EventSourceHttpClient`. The method
-:method:`Symfony\\Component\\HttpClient\\Response\\AsyncResponse::stream` takes an
-optional timeout argument.
-The :class:`Symfony\\Component\\HttpClient\\Chunk\\ServerSentEvent` is a special chunk
-capable of parsing an event stream as specified by the `EventSource`_ specification.
-
 Interoperability
 ----------------
 
@@ -1465,4 +1470,5 @@ However, using ``MockResponse`` allows simulating chunked responses and timeouts
 .. _`libcurl`: https://curl.haxx.se/libcurl/
 .. _`amphp/http-client`: https://packagist.org/packages/amphp/http-client
 .. _`cURL options`: https://www.php.net/manual/en/function.curl-setopt.php
+.. _`Server-sent events`: https://html.spec.whatwg.org/multipage/server-sent-events.html
 .. _`EventSource`:  https://www.w3.org/TR/eventsource/#eventsource