[10.x] Add support for streamed JSON Response

[pelmered]

This adds support for the StreamedJsonResponse that was added in Symfony 6.3.

Here is the Symfony documentation for this feature:
https://symfony.com/doc/6.3/components/http_foundation.html#streaming-a-json-response

This is how it can be used in Laravel with this PR:

<?php

namespace App\Http\Controllers;

use Generator;
use App\Models\User;

class ExampleController extends Controller
{
    public function index()
    {
        return response()->streamJson([
            'users' => $this->yieldUsers(),
        ]);
    }

    protected function yieldUsers(): Generator
    {
        foreach (User::query()->cursor() as $user) {
            yield $user;
        }
    }
}

The main benefits of streamed responses is that it uses a lot less memory and can be a lot faster, especially for very large responses. You can yield data that flushes straight into the response stream and the client can start to process the data before all the data is ready and sent on the server side.

I also added a test helper:

$response->assertStreamedJsonContent([
    'data' => [
        ['id' => 1],
        ['id' => 2],
        ['id' => 3],
    ],
]);

I also added some test, but I'm not sure if they are enough.

[amcsi]

Is there some counterpart to this for reading JSON requests streamed?

[pelmered]

Is there some counterpart to this for reading JSON requests streamed?

I haven't super much experience with this just yet, but I have read some theory and I am going to implement this in our application the next weeks.

Do you mean server side or client side?
PHP is not that well equipped to handle this in a good way I think. With node you can use something like stream-json and with JS on the frontend you can consume this with fetch and some additional parameters.
I can write an article about this when I have tested everything out. Maybe also add some documentation about this in the Laravel docs?

[JosephSilber]

@pelmered In your example, what's the point of the yieldUsers method? Can the user cursor not be passed off directly?

Would this not work?

response()->streamJson([
    'users' => User::cursor(),
]);

[JosephSilber]

Do you mean server side or client side?

PHP is not that well equipped to handle this in a good way I think.

While it seems @amcsi was asking about the client, I just want to give a shoutout to @cerbero90's excellent Lazy JSON PHP package 👌

[cerbero90]

@JosephSilber honoured to be mentioned by the Jedi master of Lazy collections! 🙏

[tomgrohl]

Looks like this PR was based on an article I wrote here: https://blog.devgenius.io/how-to-stream-json-responses-in-laravel-9-and-10-6eccd67b0d65

You can see there has been a copy/paste for this section:

/** @var TestResponse $this */
$this->baseResponse = new JsonResponse(
    getResponseContent($this->baseResponse),
    $this->baseResponse->getStatusCode(),
    $this->baseResponse->headers->all(),
    0,
    true
);

FYI /** @var TestResponse $this */ was only needed because I was declaring a test response macro, so this could have been left out

It would have been nice to have been cited on this.

[ppwalks24]

I've seen this prior as stated above. Plagiarism springs to mind!

[JosephSilber]

@tomgrohl nice work 👍

Is there a reason the cursor can't be used directly?

[tomgrohl]

@JosephSilber thanks.

I think I tried something like that but it didn't work. I'm pretty sure I ended up with an empty array in my response. I'm not at a computer to confirm this.

I think this is because the logic written by Symfony requires a closure to be passed that is a generator.

When you loop via the cursor call, this yields from a generator, then you yield from the outer closure too.

This is how I understood it from reading Symfony's docs before I wrote the article.

[pelmered]

Looks like this PR was based on an article I wrote here: https://blog.devgenius.io/how-to-stream-json-responses-in-laravel-9-and-10-6eccd67b0d65

You can see there has been a copy/paste for this section:

/** @var TestResponse $this */
$this->baseResponse = new JsonResponse(
    getResponseContent($this->baseResponse),
    $this->baseResponse->getStatusCode(),
    $this->baseResponse->headers->all(),
    0,
    true
);

FYI /** @var TestResponse $this */ was only needed because I was declaring a test response macro, so this could have been left out

It would have been nice to have been cited on this.

I did the whole implementation by just looking at the Symfony documentation.
At the end I realised I might need some testing in the PR and I wasn't sure how to do that in PHP. That is probably when I found that article through some Googling. In the end, I ended up not using that code anyway as it was better to just use assertStreamedContent instead.

So why would I cite you?

[cerbero90]

@JosephSilber according to the implementation all sort of objects are supported:

• iterables will be traversed
• all other objects will be simply json encoded

so in short, this is possible:

response()->streamJson([
    'users' => User::cursor(),
]);

as the lazy collection will be iterated 👍

side note for @pelmered: thanks for this PR! :) it would also be great to add the method streamJson() to the Illuminate\Contracts\Routing\ResponseFactory interface

[tomgrohl]

@cerbero90 thanks for confirming.

I was retesting this morning to check if it worked. Makes it nicer and easier to implement if you don't have to write the generator closure.

@pelmered If you didn't use my work then thats fine, no need to cite.

[tomgrohl]

As a side note I've updated my article to say its now in Laravel from 10.43: https://blog.devgenius.io/how-to-stream-json-responses-in-laravel-9-and-10-6eccd67b0d65

[pelmered]

@JosephSilber according to the implementation all sort of objects are supported:

* iterables will be traversed

* all other objects will be simply json encoded

so in short, this is possible:

response()->streamJson([
    'users' => User::cursor(),
]);

as the lazy collection will be iterated 👍

side note for @pelmered: thanks for this PR! :) it would also be great to add the method streamJson() to the Illuminate\Contracts\Routing\ResponseFactory interface

Yes, that sounds like a good addition. I will see if I can add that.

[macropay-solutions]

@pelmered
We just finished implementing this StreamedJsonResponse in our cruFd lib suite and we saw it was not streaming at all, but just builds the response in output buffer until it fills the memory if the table is big enough.

In symfony documentation they mention that you should use flush once in a while.

We did flush after each 100 rows and also we put a sleep after flushing, but no luck.
The memory issue persisted.

Analog with ob_flush().

We tested this on our demo page/website. Could there be a server setup that prevents streaming or is this an issue from symfony?

Update

We set in php.ini

output_buffering = 1024

and then the response changed to

{
    "has_more_pages": false,
    "sums": {
        "value": null
    },
    "avgs": {
        "value_avg": null
    },
    "mins": {
        "value_min": null,
        "created_at_min": null
    },
    "maxs": {
        "value_max": null,
        "created_at_max": null
    },
    "index_required_on_filtering": [
        "id",
        "parent_id",
        "client_id",
        "created_at",
        "currency",
        "value"
    ],
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "per_page": 3748918,
    "to": 3748918,
    "total": 3748918,
    "data":

Previously it was valid json but data did not contain any rows, just a "message": "Server error"

Lets continue the discussion here: #55509