feature #2298 [Turbo] Support custom TurboStreamResponse actions (DRaichev)

This PR was merged into the 2.x branch.

Discussion
----------

[Turbo] Support custom TurboStreamResponse actions

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

The current implementation of TurboStream & TurboStreamResponse has no generic action (only the predefined turbo actions) and what's more the class is marked as final, which does not allow adding support for more actions. I think the wrap function should be public or have a public function "custom" that exposes the functionality (I've opted for the latter)

I really like this library: https://github.com/marcoroth/turbo_power
It adds additional simple actions. For example I use set/delete attributes to enable/disable UI elements

This change will allow people to use this or similar libraries, or even build their own custom actions if they want to.

There is no impact to the rest of the functionality or DX

There is a minor change to the wrap function, it now accepts an array of attributes instead of a string. It builds the string from the array of attributes, and adds a leading space. This aims to prevent errors, as the previous implementation needs the $attr argument to start with a blank space otherwise it would produce invalid html

Commits
-------

d29e4d9 Add support for custom actions in `TurboStream` and `TurboStreamResponse`

Author: Kocal

src/Turbo/CHANGELOG.md

@@ -4,6 +4,7 @@
 
 -   Add `<twig:Turbo:Stream>` component
 -   Add `<twig:Turbo:Frame>` component
+-   Add support for custom actions in `TurboStream` and `TurboStreamResponse`
 
 ## 2.21.0
 

src/Turbo/src/Helper/TurboStream.php

@@ -86,6 +86,34 @@ public static function refresh(?string $requestId = null): string
         return \sprintf('<turbo-stream action="refresh" request-id="%s"></turbo-stream>', htmlspecialchars($requestId));
     }
 
+    /**
+     * Custom action and attributes.
+     *
+     * Set boolean attributes (e.g., `disabled`) by providing the attribute name as key with `null` as value.
+     *
+     * @param array<string, string|int|float|null> $attr
+     */
+    public static function action(string $action, string $target, string $html, array $attr = []): string
+    {
+        if (\array_key_exists('action', $attr) || \array_key_exists('targets', $attr)) {
+            throw new \InvalidArgumentException('The "action" and "targets" attributes are reserved and cannot be used.');
+        }
+
+        $attrString = '';
+        foreach ($attr as $key => $value) {
+            $key = htmlspecialchars($key);
+            if (null === $value) {
+                $attrString .= \sprintf(' %s', $key);
+            } elseif (\is_int($value) || \is_float($value)) {
+                $attrString .= \sprintf(' %s="%s"', $key, $value);
+            } else {
+                $attrString .= \sprintf(' %s="%s"', $key, htmlspecialchars($value));
+            }
+        }
+
+        return self::wrap(htmlspecialchars($action), $target, $html, $attrString);
+    }
+
     private static function wrap(string $action, string $target, string $html, string $attr = ''): string
     {
         return \sprintf(<<<EOHTML

src/Turbo/src/TurboStreamResponse.php

@@ -104,4 +104,20 @@ public function refresh(?string $requestId = null): static
 
         return $this;
     }
+
+    /**
+     * Custom action and attributes.
+     *
+     * Set boolean attributes (e.g., `disabled`) by providing the attribute name as key with `null` as value.
+     *
+     * @param array<string, string|int|float|null> $attr
+     *
+     * @return $this
+     */
+    public function action(string $action, string $target, string $html, array $attr = []): static
+    {
+        $this->setContent($this->getContent().TurboStream::action($action, $target, $html, $attr));
+
+        return $this;
+    }
 }

src/Turbo/tests/Helper/TurboStreamTest.php

@@ -76,4 +76,32 @@ public function testRefreshWithId(): void
             TurboStream::refresh('a"b')
         );
     }
+
+    public function testCustom(): void
+    {
+        $this->assertSame(<<<EOHTML
+            <turbo-stream action="customAction" targets="some[&quot;selector&quot;]" someAttr="someValue" boolAttr intAttr="0" floatAttr="3.14">
+                <template><div>content</div></template>
+            </turbo-stream>
+            EOHTML,
+            TurboStream::action('customAction', 'some["selector"]', '<div>content</div>', ['someAttr' => 'someValue', 'boolAttr' => null, 'intAttr' => 0, 'floatAttr' => 3.14])
+        );
+    }
+
+    /**
+     * @dataProvider customThrowsExceptionDataProvider
+     *
+     * @param array<string, string|int|float|null> $attr
+     */
+    public function testCustomThrowsException(string $action, string $target, string $html, array $attr): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        TurboStream::action($action, $target, $html, $attr);
+    }
+
+    public static function customThrowsExceptionDataProvider(): \Generator
+    {
+        yield ['customAction', 'some["selector"]', '<div>content</div>', ['action' => 'someAction']];
+        yield ['customAction', 'some["selector"]', '<div>content</div>', ['targets' => 'someTargets']];
+    }
 }