[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? 😇

[smnandre]

TurboStreamResponse ?

[smnandre]

Both HttpFoundation StreamedResponse and StreamedJsonResponse have specialized constructors.

What if we made TurboStream a stringable object and have this kind of signature

/**
 * @param string|Stringable|iterable<string|Stringable> $stream
 */ 
public function __construct(string|iterable $streams = '', int $status = 200, array $headers = [])
{

(Genuine suggestion, not sure what would be the best DX here)

[smnandre]

Suggested change

	public function __construct(?string $content = '', int $status = 200, array $headers = [])
	/**
	* @param array<string, string|string[]> $headers
	*/
	public function __construct(?string $content = '', int $status = 200, array $headers = [])

To please the CI :)

[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.