Send live action arguments to backend

Author: norkunas

src/LiveComponent/README.md

@@ -541,6 +541,56 @@ class RandomNumberComponent
 }
 ```
 
+##### Passing arguments to live action
+
+You can also provide custom arguments to your action. For example Symfony Form CollectionType needs some JavaScript
+to make form dynamic, but it can be avoided.
+
+In component template we use "add entry" and "remove" entry buttons and configure the custom actions that are
+implemented in your custom live component. Specific part for remove entry is using an named action argument to provide
+the index of the entry which we need to remove. You can provide as many arguments as you need.
+
+```twig
+<form>
+    <div>
+        Entries:
+        <button data-action="live#action" data-action-name="addEntry">Add new entry</button>
+    </div>
+    {% for entry in this.formValues.entries %}
+        .. render your entry ..
+        <button data-action="live#action" data-action-name="removeEntry(index={{ loop.index0 }})">remove entry</button>
+    {% endfor %}
+</form>
+```
+
+In component for custom arguments to be injected we need to use `#[LiveArg('..')]` attribute, otherwise it would be
+ignored.
+
+```php
+// src/Components/CollectionComponent.php
+namespace App\Components;
+
+// ...
+use Symfony\UX\LiveComponent\Attribute\LiveArg;
+use Psr\Log\LoggerInterface;
+
+class CollectionComponent
+{
+    // ...
+
+    public function addEntry()
+    {
+        $this->formValues['entries'][] = [];
+    }
+
+    #[LiveAction]
+    public function removeEntry(#[LiveArg] int $index)
+    {
+        array_splice($this->formValues['entries'], $index, 1);
+    }
+}
+```
+
 ### Actions and CSRF Protection
 
 When you trigger an action, a POST request is sent that contains

src/LiveComponent/assets/dist/live_controller.js

@@ -1070,7 +1070,7 @@ class default_1 extends Controller {
         directives.forEach((directive) => {
             const _executeAction = () => {
                 this._clearWaitingDebouncedRenders();
-                this._makeRequest(directive.action);
+                this._makeRequest(directive.action, directive.named);
             };
             let handled = false;
             directive.modifiers.forEach((modifier) => {
@@ -1162,11 +1162,14 @@ class default_1 extends Controller {
             }, this.debounceValue || DEFAULT_DEBOUNCE);
         }
     }
-    _makeRequest(action) {
+    _makeRequest(action, args) {
         const splitUrl = this.urlValue.split('?');
         let [url] = splitUrl;
         const [, queryString] = splitUrl;
         const params = new URLSearchParams(queryString || '');
+        if (typeof args === 'object' && Object.keys(args).length > 0) {
+            params.set('args', new URLSearchParams(args).toString());
+        }
         const fetchOptions = {};
         fetchOptions.headers = {
             'Accept': 'application/vnd.live-component+json',

src/LiveComponent/assets/src/live_controller.ts

@@ -144,7 +144,7 @@ export default class extends Controller {
                 // taking precedence
                 this._clearWaitingDebouncedRenders();
 
-                this._makeRequest(directive.action);
+                this._makeRequest(directive.action, directive.named);
             }
 
             let handled = false;
@@ -296,12 +296,16 @@ export default class extends Controller {
         }
     }
 
-    _makeRequest(action: string|null) {
+    _makeRequest(action: string|null, args: Record<string,unknown>) {
         const splitUrl = this.urlValue.split('?');
         let [url] = splitUrl
         const [, queryString] = splitUrl;
         const params = new URLSearchParams(queryString || '');
 
+        if (typeof args === 'object' && Object.keys(args).length > 0) {
+            params.set('args', new URLSearchParams(args).toString());
+        }
+
         const fetchOptions: RequestInit = {};
         fetchOptions.headers = {
             'Accept': 'application/vnd.live-component+json',

src/LiveComponent/assets/test/controller/action.test.ts

@@ -35,6 +35,8 @@ describe('LiveController Action Tests', () => {
                 data-action="live#action"
                 data-action-name="save"
             >Save</button>
+
+            <button data-action="live#action" data-action-name="sendNamedArgs(a=1, b=2, c=3)">Send named args</button>
         </div>
     `;
 
@@ -64,4 +66,15 @@ describe('LiveController Action Tests', () => {
 
         expect(postMock.lastOptions().body.get('comments')).toEqual('hi WEAVER');
     });
+
+    it('Sends action named args', async () => {
+        const data = { comments: 'hi' };
+        const { element } = await startStimulus(template(data));
+
+        fetchMock.postOnce('http://localhost/_components/my_component/sendNamedArgs?values=a%3D1%26b%3D2%26c%3D3', {
+            html: template({ comments: 'hi' }),
+        });
+
+        getByText(element, 'Send named args').click();
+    });
 });

src/LiveComponent/src/Attribute/LiveArg.php

@@ -0,0 +1,46 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\UX\LiveComponent\Attribute;
+
+/**
+ * @author Tomas Norkūnas <norkunas.tom@gmail.com>
+ *
+ * @experimental
+ */
+#[\Attribute(\Attribute::TARGET_PARAMETER)]
+final class LiveArg
+{
+    public function __construct(public ?string $name = null)
+    {
+    }
+
+    /**
+     * @return array<string, string>
+     */
+    public static function liveArgs(object $component, string $action): array
+    {
+        $method = new \ReflectionMethod($component, $action);
+        $liveArgs = [];
+
+        foreach ($method->getParameters() as $parameter) {
+            foreach ($parameter->getAttributes(self::class) as $liveArg) {
+                /** @var LiveArg $attr */
+                $attr = $liveArg->newInstance();
+                $parameterName = $parameter->getName();
+
+                $liveArgs[$parameterName] = $attr->name ?? $parameterName;
+            }
+        }
+
+        return $liveArgs;
+    }
+}

src/LiveComponent/src/EventListener/LiveComponentSubscriber.php

@@ -29,6 +29,7 @@
 use Symfony\Component\Security\Csrf\CsrfTokenManagerInterface;
 use Symfony\Contracts\Service\ServiceSubscriberInterface;
 use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
+use Symfony\UX\LiveComponent\Attribute\LiveArg;
 use Symfony\UX\LiveComponent\LiveComponentHydrator;
 use Symfony\UX\TwigComponent\ComponentFactory;
 use Symfony\UX\TwigComponent\ComponentRenderer;
@@ -141,11 +142,21 @@ public function onKernelController(ControllerEvent $event): void
 
         $this->container->get(LiveComponentHydrator::class)->hydrate($component, $data);
 
+        $request->attributes->set('_component', $component);
+
+        if (!\is_string($queryString = $request->query->get('args'))) {
+            return;
+        }
+
         // extra variables to be made available to the controller
         // (for "actions" only)
-        parse_str($request->query->get('values'), $values);
-        $request->attributes->add($values);
-        $request->attributes->set('_component', $component);
+        parse_str($queryString, $args);
+
+        foreach (LiveArg::liveArgs($component, $action) as $parameter => $arg) {
+            if (isset($args[$arg])) {
+                $request->attributes->set($parameter, $args[$arg]);
+            }
+        }
     }
 
     public function onKernelView(ViewEvent $event): void

src/LiveComponent/tests/Fixture/Component/Component6.php

@@ -0,0 +1,51 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\UX\LiveComponent\Tests\Fixture\Component;
+
+use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
+use Symfony\UX\LiveComponent\Attribute\LiveAction;
+use Symfony\UX\LiveComponent\Attribute\LiveArg;
+use Symfony\UX\LiveComponent\Attribute\LiveProp;
+use Symfony\UX\LiveComponent\DefaultActionTrait;
+
+/**
+ * @author Tomas Norkūnas <norkunas.tom@gmail.com>
+ */
+#[AsLiveComponent('component6')]
+class Component6
+{
+    use DefaultActionTrait;
+
+    #[LiveProp]
+    public bool $called = false;
+
+    #[LiveProp]
+    public $arg1;
+
+    #[LiveProp]
+    public $arg2;
+
+    #[LiveProp]
+    public $arg3;
+
+    #[LiveAction]
+    public function inject(
+        #[LiveArg] string $arg1,
+        #[LiveArg] int $arg2,
+        #[LiveArg('custom')] float $arg3,
+    ) {
+        $this->called = true;
+        $this->arg1 = $arg1;
+        $this->arg2 = $arg2;
+        $this->arg3 = $arg3;
+    }
+}

src/LiveComponent/tests/Fixture/Kernel.php

@@ -26,6 +26,7 @@
 use Symfony\UX\LiveComponent\Tests\Fixture\Component\Component1;
 use Symfony\UX\LiveComponent\Tests\Fixture\Component\Component2;
 use Symfony\UX\LiveComponent\Tests\Fixture\Component\Component3;
+use Symfony\UX\LiveComponent\Tests\Fixture\Component\Component6;
 use Symfony\UX\TwigComponent\TwigComponentBundle;
 use Twig\Environment;
 
@@ -65,12 +66,14 @@ protected function configureContainer(ContainerBuilder $c, LoaderInterface $load
         $componentA = $c->register(Component1::class)->setAutoconfigured(true)->setAutowired(true);
         $componentB = $c->register(Component2::class)->setAutoconfigured(true)->setAutowired(true);
         $componentC = $c->register(Component3::class)->setAutoconfigured(true)->setAutowired(true);
+        $componentF = $c->register(Component6::class)->setAutoconfigured(true)->setAutowired(true);
 
         if (self::VERSION_ID < 50300) {
             // add tag manually
             $componentA->addTag('twig.component', ['key' => 'component1'])->addTag('controller.service_arguments');
             $componentB->addTag('twig.component', ['key' => 'component2', 'default_action' => 'defaultAction'])->addTag('controller.service_arguments');
             $componentC->addTag('twig.component', ['key' => 'component3'])->addTag('controller.service_arguments');
+            $componentF->addTag('twig.component', ['key' => 'component6'])->addTag('controller.service_arguments');
         }
 
         $sessionConfig = self::VERSION_ID < 50300 ? ['storage_id' => 'session.storage.mock_file'] : ['storage_factory_id' => 'session.storage.factory.mock_file'];

src/LiveComponent/tests/Fixture/templates/components/component6.html.twig

@@ -0,0 +1,7 @@
+<div
+    {{ init_live_component(this) }}
+>
+    Arg1: {{ this.called ? this.arg1 : 'not provided' }}
+    Arg2: {{ this.called ? this.arg2 : 'not provided' }}
+    Arg3: {{ this.called ? this.arg3 : 'not provided' }}
+</div>

src/LiveComponent/tests/Functional/EventListener/LiveComponentSubscriberTest.php

@@ -17,6 +17,7 @@
 use Symfony\UX\LiveComponent\Tests\ContainerBC;
 use Symfony\UX\LiveComponent\Tests\Fixture\Component\Component1;
 use Symfony\UX\LiveComponent\Tests\Fixture\Component\Component2;
+use Symfony\UX\LiveComponent\Tests\Fixture\Component\Component6;
 use Symfony\UX\LiveComponent\Tests\Fixture\Entity\Entity1;
 use Symfony\UX\TwigComponent\ComponentFactory;
 use Zenstruck\Browser\Response\HtmlResponse;
@@ -240,4 +241,43 @@ public function testCanRedirectFromComponentAction(): void
             ->assertJsonMatches('redirect_url', '/')
         ;
     }
+
+    public function testInjectsLiveArgs(): void
+    {
+        /** @var LiveComponentHydrator $hydrator */
+        $hydrator = self::getContainer()->get('ux.live_component.component_hydrator');
+
+        /** @var ComponentFactory $factory */
+        $factory = self::getContainer()->get('ux.twig_component.component_factory');
+
+        /** @var Component6 $component */
+        $component = $factory->create('component6');
+
+        $dehydrated = $hydrator->dehydrate($component);
+        $token = null;
+
+        $dehydrated['args'] = http_build_query(['arg1' => 'hello', 'arg2' => 666, 'custom' => '33.3']);
+
+        $this->browser()
+            ->throwExceptions()
+            ->get('/_components/component6?'.http_build_query($dehydrated))
+            ->assertSuccessful()
+            ->assertHeaderContains('Content-Type', 'html')
+            ->assertContains('Arg1: not provided')
+            ->assertContains('Arg2: not provided')
+            ->assertContains('Arg3: not provided')
+            ->use(function (HtmlResponse $response) use (&$token) {
+                // get a valid token to use for actions
+                $token = $response->crawler()->filter('div')->first()->attr('data-live-csrf-value');
+            })
+            ->post('/_components/component6/inject?'.http_build_query($dehydrated), [
+                'headers' => ['X-CSRF-TOKEN' => $token],
+            ])
+            ->assertSuccessful()
+            ->assertHeaderContains('Content-Type', 'html')
+            ->assertContains('Arg1: hello')
+            ->assertContains('Arg2: 666')
+            ->assertContains('Arg3: 33.3')
+        ;
+    }
 }