[Turbo] Add Helper/TurboStream::append() et al. methods

[nicolas-grekas]

Q	A
Bug fix?	no
New feature?	yes
Issues	-
License	MIT

For thoughts, this might help, WDYT?

return new TurboResponse(TurboStream::append($target, $html));

(Note that I'm also wondering about having a twig component to render streams from the twig side, stay tuned)

[Kocal]

I'm not a Turbo user, but I think it can be useful yes.

Just, can you add some documentation for this new feature please? And also fix failing checks (IMO we can ignore the error found by PHPStan).

Thanks! :)

[nicolas-grekas]

Updated

[rvmourik]

Great addition imho, but what about multiple streams in a single response? Or is that the Twig solution you are talking about @nicolas-grekas?

return new TurboResponse(TurboStream::append($target, $html));

Regarding DX it is not optimal to have this I guess:

return new TurboResponse(TurboStream::append($target, $html) . TurboStream::replace($target2, $html2));

Is this something to consider?

[smnandre]

Thanks a lot @nicolas-grekas! More comments tomorrow :)

[nicolas-grekas]

@rvmourik concatenation FTW indeed. I don't see a better option. In the end, any alternative would just be a fancy way to do concatenation.

[rvmourik]

@rvmourik concatenation FTW indeed. I don't see a better option. In the end, any alternative would just be a fancy way to do concatenation.

@nicolas-grekas thanks for the quick reply.

I know the TurboResponse is extending the base Response class but if we take a look at the JsonResponse there is also an option to pass an array or a mixed value, when it is mixed in the end is converts it to an ArrayObject. Could the TurboResponse do something similar, always convert the passed stream(s) to be a collection of streams and processing them before passing it to the base Response?

Maybe I am overthinking it? 😇

[javiereguiluz]

If we decide to add some helpers to make using Turbo more user-friendly, what if we all DX and provide a fluent interface to not deal with any internal details?

return TurboResponse()
    ->append($targetId, $html)
    ->prepend($targetId, $html)
    ->replace($targetId, $html, $method = 'morph')
    ->update($targetId, $html, $method = 'morph')
    ->remove($targetId, $html)
    ->before($targetId, $html)
    ->after($targetId, $html)
    // useful if the action (append, prepend, etc.) is a PHP variable:
    ->stream($action, $targetId, $html)
;

@rvmourik your example now would look like this:

// before
return new TurboResponse(TurboStream::append($target, $html) . TurboStream::replace($target2, $html2));

// after
return new TurboResponse()
    ->append($target, $html)
    ->append($target2, $html2)
;

There's a final consideration, which is not covered either in the current proposal of this PR. In addition to target (the targetID), you can use targets (a CSS selector) to apply the stream to multiple targets (See https://turbo.hotwired.dev/handbook/streams#actions-with-multiple-targets).

Adding an optional targets param would look ugly in my opinion:

return TurboResponse()
    ->append(string|null $targetId, string|null $targets, string $html)
    ->prepend(string|null $targetId, string|null $targets, string $html)
    // ...

We could add a *All() series of methods:

return TurboResponse()
    ->append(string $targetId, string $html)
    ->appendAll(string $targets, string $html)

    ->prepend(string $targetId, string $html)
    ->prependAll(string $targets, string $html)
    // ...

What do you think?

[rvmourik]

If we decide to add some helpers to make using Turbo more user-friendly, what if we all DX and provide a fluent interface to not deal with any internal details?

return TurboResponse()
    ->append($targetId, $html)
    ->prepend($targetId, $html)
    ->replace($targetId, $html, $method = 'morph')
    ->update($targetId, $html, $method = 'morph')
    ->remove($targetId, $html)
    ->before($targetId, $html)
    ->after($targetId, $html)
    // useful if the action (append, prepend, etc.) is a PHP variable:
    ->stream($action, $targetId, $html)
;

@rvmourik your example now would look like this:

// before
return new TurboResponse(TurboStream::append($target, $html) . TurboStream::replace($target2, $html2));

// after
return new TurboResponse()
    ->append($target, $html)
    ->append($target2, $html2)
;

There's a final consideration, which is not covered either in the current proposal of this PR. In addition to target (the targetID), you can use targets (a CSS selector) to apply the stream to multiple targets (See https://turbo.hotwired.dev/handbook/streams#actions-with-multiple-targets).

Adding an optional targets param would look ugly in my opinion:

return TurboResponse()
    ->append(string|null $targetId, string|null $targets, $html)
    ->prepend(string|null $targetId, string|null $targets, $html)
    // ...

We could add a *All() series of methods:

return TurboResponse()
    ->append(string $targetId, $html)
    ->appendAll(string $targets, $html)

    ->prepend(string $targetId, string $html)
    ->prependAll(string $targets, $html)
    // ...

What do you think?

I think this is a good suggestion, maybe in a future PR the same can be done with adding a helper for a regular turbo frame. I find my self often doing one of the following:

a) creating a twig file only with the frame and HTML in it
b) manually building a response like in the helper in this PR en load the twig file between the tag in the response.

Thanks all.

[nicolas-grekas]

what if we all DX and provide a fluent interface

Works for me, I added the fluent methods to the TurboStreamResponse class.
Note that I don't know yet if that should be the recommended way to generate turbo stream: the drawback of this approach is that it splits targets from actual HTML, so that it can be easy to forget to update a target after updating a template. Putting the stream tags in the template that they target would improve this by providing locality.

In addition to target (the targetID), you can use targets (a CSS selector) to apply the stream to multiple targets

You might have missed this in the attached patch: this PR uses only targets, with an "s". That means you have to use #foo to target id foo. To me, this is the most empowering and DX-friendly way to express the target. Using target (no "s") provides zero benefits.

[nicolas-grekas]

Note the "s" to targets, and the docblock comments: we support only CSS selectors, not pure IDs (CSS selectors are more capable anyway).

[nicolas-grekas]

PR ready IMHO (failure unrelated IIUC)

[nicolas-grekas]

All green :)

[Kocal]

Thank you @nicolas-grekas.