Update to new version of the class

Author: alexander-schranz

components/http_foundation.rst

@@ -634,41 +634,102 @@ represented by a PHP callable instead of a string::
 Streaming a JSON Response
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. versionadded:: 6.2
+.. versionadded:: 6.3
+
+    The :class:`Symfony\\Component\\HttpFoundation\\StreamedJsonResponse` class was
+    introduced in Symfony 6.3.
+
+The :class:`Symfony\\Component\\HttpFoundation\\StreamedJsonResponse` allows an API to
+return a lot of data as JSON and keep the used resources low by make usage of Generators.
 
-The :class:`Symfony\\Component\\HttpFoundation\\StreamedJsonResponse` class allows
-an API to return a lot of data as JSON and keep the used resources low by make usage
-of Generators.
+It expects an array which represents the JSON structure and the list which should be
+streamed are represented in the array as ``\Generator``. It also supports any kind of
+Traversable containing JSON Serializable data for a good developer experience,
+but for keep the resources usage low as possible it is recommended to use ``\Generators``,
+as they the advantages that only the current returned data need to be keep in memory.
 
-It expects a JSON structure with one or multiple replacers identifiers, as example
-the `'__articles__'`. As a second argument it requires one or multiple Generators
-which items can be converted to a JSON via ``json_encode`` method. The key of the
-Generators requires to be the used replacer identifiers::
+The response will stream the JSON with generators in to most efficient way and keep resources as low as possible::
 
     use Symfony\Component\HttpFoundation\StreamedJsonResponse;
 
+    function loadArticles(): \Generator { // any method or function returning a Generator
+         yield ['title' => 'Article 1'];
+         yield ['title' => 'Article 2'];
+         yield ['title' => 'Article 3'];
+    };
+
     $response = new StreamedJsonResponse(
-        // json structure with replace identifiers
+        // json structure with generators in which will be streamed as a list
         [
             '_embedded' => [
-                'articles' => '__articles__',
+                'articles' => loadArticles(), // any \Generator can be used which will be streamed as list of data
             ],
         ],
-        // array of generators with replace identifier used as key
-        [
-            '__articles__' => (function (): \Generator { // any method or function returning a Generator
-                 yield ['title' => 'Article 1'];
-                 yield ['title' => 'Article 2'];
-                 yield ['title' => 'Article 3'];
-            })(),
-        ]
     );
 
 .. tip::
 
     If loading data via doctrine the ``toIterable`` method of ``Doctrine`` can be
     used to keep also the resources low and fetch only one row one by one.
-    See the `Doctrine Batch processing`_ documentation for more.
+    See the `Doctrine Batch processing`_ documentation for more::
+
+        public function __invoke(): Response
+        {
+            return new StreamedJsonResponse(
+                [
+                    '_embedded' => [
+                        'articles' => $this->loadArticles(),
+                    ],
+                ],
+            );
+        }
+
+        public function loadArticles(): \Generator
+        {
+            $queryBuilder = $entityManager->createQueryBuilder();
+            $queryBuilder->from(Article::class, 'article');
+            $queryBuilder->select('article.id')
+                ->addSelect('article.title')
+                ->addSelect('article.description');
+
+            return $queryBuilder->getQuery()->toIterable();
+        }
+
+.. tip::
+
+    If you have a lot of data to be returned you maybe want to call the
+    PHP `flush <https://www.php.net/manual/en/function.flush.php>`__ method between
+    to flush the response after every specific count of items::
+
+        public function __invoke(): Response
+        {
+            return new StreamedJsonResponse(
+                [
+                    '_embedded' => [
+                        'articles' => $this->loadArticles(),
+                    ],
+                ],
+            );
+        }
+
+        public function loadArticles(): \Generator
+        {
+            $queryBuilder = $entityManager->createQueryBuilder();
+            $queryBuilder->from(Article::class, 'article');
+            $queryBuilder->select('article.id')
+                ->addSelect('article.title')
+                ->addSelect('article.description');
+
+            $count = 0;
+            foreach ($queryBuilder->getQuery()->toIterable() as $article) {
+                yield $article;
+
+                if (++$count % 100 === 0) {
+                    flush();
+                }
+            }
+        }
+
 
 Serving Files
 ~~~~~~~~~~~~~