minor #17301 [HttpFoundation] Add documentation for StreamedJsonResponse (alexander-schranz)

This PR was squashed before being merged into the 6.3 branch. Discussion ---------- [HttpFoundation] Add documentation for `StreamedJsonResponse` Docs for: symfony/symfony#47709 # TODO - [x] Example of Flush Handling Commits ------- 8a285e3 [HttpFoundation] Add documentation for `StreamedJsonResponse`

Author: javiereguiluz

components/http_foundation.rst

@@ -631,6 +631,103 @@ represented by a PHP callable instead of a string::
 
 .. _component-http-foundation-serving-files:
 
+Streaming a JSON Response
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. 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.
+
+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 as 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.
+
+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 generators in which will be streamed as a list
+ [
+ '_embedded' => [
+ 'articles' => loadArticles(), // any \Generator can be used which will be streamed as list of data
+ ],
+ ],
+ );
+
+.. tip::
+
+ If loading data via doctrine the ``toIterable`` method of ``Doctrine`` can be
+ used to keep the resources low and fetch only row by row.
+ 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 may 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
 ~~~~~~~~~~~~~
 
@@ -866,3 +963,4 @@ Learn More
 .. _`JSON Hijacking`: https://haacked.com/archive/2009/06/25/json-hijacking.aspx/
 .. _OWASP guidelines: https://cheatsheetseries.owasp.org/cheatsheets/AJAX_Security_Cheat_Sheet.html#always-return-json-with-an-object-on-the-outside
 .. _RFC 8674: https://tools.ietf.org/html/rfc8674
+.. _Doctrine Batch processing: https://www.doctrine-project.org/projects/doctrine-orm/en/2.14/reference/batch-processing.html#iterating-results