Add alias option to url query mapping

Author: squrious

src/LiveComponent/CHANGELOG.md

@@ -4,6 +4,7 @@
 
 -   Add `modifier` option in `LiveProp` so options can be modified at runtime.
 -   Fix collections hydration with serializer in LiveComponents
+-   Add `UrlMapping` configuration object for URL bindings in LiveComponents
 
 ## 2.16.0
 

src/LiveComponent/assets/test/controller/query-binding.test.ts

@@ -144,7 +144,6 @@ describe('LiveController query string binding', () => {
         expectCurrentSearch().toEqual('?prop=');
     });
 
-
     it('updates the URL with props changed by the server', async () => {
         const test = await createTest({ prop: ''}, (data: any) => `
             <div ${initComponent(data, {queryMapping: {prop: {name: 'prop'}}})}>
@@ -165,4 +164,26 @@ describe('LiveController query string binding', () => {
 
         expectCurrentSearch().toEqual('?prop=foo');
     });
+
+    it('uses custom name instead of prop name in the URL', async () => {
+        const test = await createTest({ prop1: ''}, (data: any) => `
+            <div ${initComponent(data, { queryMapping: {prop1: {name: 'alias1'} }})}></div>
+        `)
+
+        // Set value
+        test.expectsAjaxCall()
+            .expectUpdatedData({prop1: 'foo'});
+
+        await test.component.set('prop1', 'foo', true);
+
+        expectCurrentSearch().toEqual('?alias1=foo');
+
+        // Remove value
+        test.expectsAjaxCall()
+            .expectUpdatedData({prop1: ''});
+
+        await test.component.set('prop1', '', true);
+
+        expectCurrentSearch().toEqual('?alias1=');
+    });
 })

src/LiveComponent/doc/index.rst

@@ -2438,11 +2438,6 @@ If you load this URL in your browser, the ``LiveProp`` value will be initialized
 
     The URL is changed via ``history.replaceState()``. So no new entry is added.
 
-.. warning::
-
-    You can use multiple components with URL bindings in the same page, as long as bound field names don't collide.
-    Otherwise, you will observe unexpected behaviors.
-
 Supported Data Types
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -2486,6 +2481,65 @@ For example, if you declare the following bindings::
 And you only set the ``query`` value, then your URL will be updated to
 ``https://my.domain/search?query=my+query+string&mode=fulltext``.
 
+Controlling the Query Parameter Name
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 2.17
+
+    The ``as`` option was added in LiveComponents 2.17.
+
+
+Instead of using the prop's field name as the query parameter name, you can use the ``as`` option in your ``LiveProp``
+definition::
+
+    // ...
+    use Symfony\UX\LiveComponent\Metadata\UrlMapping;
+
+    #[AsLiveComponent]
+    class SearchModule
+    {
+        #[LiveProp(writable: true, url: new UrlMapping(as: 'q')]
+        public string $query = '';
+
+        // ...
+    }
+
+Then the ``query`` value will appear in the URL like ``https://my.domain/search?q=my+query+string``.
+
+If you need to change the parameter name on a specific page, you can leverage the :ref:`modifier <modifier>` option::
+
+    // ...
+    use Symfony\UX\LiveComponent\Metadata\UrlMapping;
+
+    #[AsLiveComponent]
+    class SearchModule
+    {
+        #[LiveProp(writable: true, url: true, modifier: 'modifyQueryProp')]
+        public string $query = '';
+
+        #[LiveProp]
+        public ?string $alias = null;
+
+        public function modifyQueryProp(LiveProp $liveProp): LiveProp
+        {
+            if ($this->alias) {
+                $liveProp = $liveProp->withUrl(new UrlMapping(as: $this->alias));
+            }
+            return $liveProp;
+        }
+    }
+
+.. code-block:: twig
+
+    <twig:SearchModule alias="q" />
+
+This way you can also use the component multiple times in the same page and avoid collisions in parameter names:
+
+.. code-block:: twig
+
+    <twig:SearchModule alias="q1" />
+    <twig:SearchModule alias="q2" />
+
 Validating the Query Parameter Values
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -2513,8 +2567,8 @@ validated. To validate it, you have to set up a `PostMount hook`_::
         #[PostMount]
         public function postMount(): void
         {
-            // Validate 'mode' field without throwing an exception, so the component can be mounted anyway and a
-            // validation error can be shown to the user
+            // Validate 'mode' field without throwing an exception, so the component can
+            // be mounted anyway and a validation error can be shown to the user
             if (!$this->validateField('mode', false)) {
                 // Do something when validation fails
             }
@@ -3450,6 +3504,8 @@ the change of one specific key::
         }
     }
 
+.. _modifier:
+
 Set LiveProp Options Dynamically
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

src/LiveComponent/src/Attribute/LiveProp.php

@@ -11,6 +11,8 @@
 
 namespace Symfony\UX\LiveComponent\Attribute;
 
+use Symfony\UX\LiveComponent\Metadata\UrlMapping;
+
 /**
  * An attribute to mark a property as a "LiveProp".
  *
@@ -97,10 +99,11 @@ public function __construct(
         private string|array|null $onUpdated = null,
 
         /**
-         * If true, this property will be synchronized with a query parameter
-         * in the URL.
+         * Whether to synchronize this property with a query parameter
+         * in the URL. Pass true to configure the mapping automatically, or a
+         * {@see UrlMapping} instance to configure the mapping.
          */
-        private bool $url = false,
+        private bool|UrlMapping $url = false,
 
         /**
          * A hook that will be called when this LiveProp is used.
@@ -111,9 +114,13 @@ public function __construct(
          *
          * @var string|null
          */
-        private string|null $modifier = null,
+        private ?string $modifier = null,
     ) {
         self::validateHydrationStrategy($this);
+
+        if (true === $url) {
+            $this->url = new UrlMapping();
+        }
     }
 
     /**
@@ -277,20 +284,20 @@ public function withOnUpdated(string|array|null $onUpdated): self
         return $clone;
     }
 
-    public function url(): bool
+    public function url(): UrlMapping|false
     {
         return $this->url;
     }
 
-    public function withUrl(bool $url): self
+    public function withUrl(bool|UrlMapping $url): self
     {
         $clone = clone $this;
-        $clone->url = $url;
+        $clone->url = (true === $url) ? new UrlMapping() : $url;
 
         return $clone;
     }
 
-    public function modifier(): string|null
+    public function modifier(): ?string
     {
         return $this->modifier;
     }

src/LiveComponent/src/Metadata/LiveComponentMetadata.php

@@ -69,7 +69,7 @@ public function getOnlyPropsThatAcceptUpdatesFromParent(array $inputProps): arra
     public function hasQueryStringBindings($component): bool
     {
         foreach ($this->getAllLivePropsMetadata($component) as $livePropMetadata) {
-            if ($livePropMetadata->queryStringMapping()) {
+            if ($livePropMetadata->urlMapping()) {
                 return true;
             }
         }

src/LiveComponent/src/Metadata/LivePropMetadata.php

@@ -51,9 +51,9 @@ public function allowsNull(): bool
         return $this->allowsNull;
     }
 
-    public function queryStringMapping(): bool
+    public function urlMapping(): ?UrlMapping
     {
-        return $this->liveProp->url();
+        return $this->liveProp->url() ?: null;
     }
 
     public function calculateFieldName(object $component, string $fallback): string

src/LiveComponent/src/Metadata/UrlMapping.php

@@ -0,0 +1,33 @@
+<?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\Metadata;
+
+/**
+ * Mapping configuration to bind a LiveProp to a URL query parameter.
+ *
+ * @author Nicolas Rigaud <squrious@protonmail.com>
+ */
+final class UrlMapping
+{
+    public function __construct(
+        /**
+         * The name of the prop that appears in the URL. If null, the LiveProp's field name is used.
+         */
+        private ?string $as = null,
+    ) {
+    }
+
+    public function getAs(): ?string
+    {
+        return $this->as;
+    }
+}

src/LiveComponent/src/Util/LiveControllerAttributesCreator.php

@@ -104,14 +104,14 @@ public function attributesForRendering(MountedComponent $mounted, ComponentMetad
         }
 
         if ($liveMetadata->hasQueryStringBindings($mounted->getComponent())) {
-            $queryMapping = [];
+            $mappings = [];
             foreach ($liveMetadata->getAllLivePropsMetadata($mounted->getComponent()) as $livePropMetadata) {
-                if ($livePropMetadata->queryStringMapping()) {
+                if ($urlMapping = $livePropMetadata->urlMapping()) {
                     $frontendName = $livePropMetadata->calculateFieldName($mounted->getComponent(), $livePropMetadata->getName());
-                    $queryMapping[$frontendName] = ['name' => $frontendName];
+                    $mappings[$frontendName] = ['name' => $urlMapping->getAs() ?? $frontendName];
                 }
             }
-            $attributesCollection->setQueryUrlMapping($queryMapping);
+            $attributesCollection->setQueryUrlMapping($mappings);
         }
 
         if ($isChildComponent) {

src/LiveComponent/src/Util/QueryStringPropsExtractor.php

@@ -41,9 +41,9 @@ public function extract(Request $request, LiveComponentMetadata $metadata, objec
         $data = [];
 
         foreach ($metadata->getAllLivePropsMetadata($component) as $livePropMetadata) {
-            if ($livePropMetadata->queryStringMapping()) {
+            if ($queryMapping = $livePropMetadata->urlMapping()) {
                 $frontendName = $livePropMetadata->calculateFieldName($component, $livePropMetadata->getName());
-                if (null !== ($value = $query[$frontendName] ?? null)) {
+                if (null !== ($value = $query[$queryMapping->getAs() ?? $frontendName] ?? null)) {
                     if ('' === $value && null !== $livePropMetadata->getType() && (!$livePropMetadata->isBuiltIn() || 'array' === $livePropMetadata->getType())) {
                         // Cast empty string to empty array for objects and arrays
                         $value = [];

src/LiveComponent/tests/Fixtures/Component/ComponentWithUrlBoundProps.php

@@ -14,6 +14,7 @@
 use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
 use Symfony\UX\LiveComponent\Attribute\LiveProp;
 use Symfony\UX\LiveComponent\DefaultActionTrait;
+use Symfony\UX\LiveComponent\Metadata\UrlMapping;
 use Symfony\UX\LiveComponent\Tests\Fixtures\Dto\Address;
 
 #[AsLiveComponent('component_with_url_bound_props')]
@@ -57,4 +58,7 @@ public function modifyProp8(LiveProp $prop): LiveProp
     {
         return $prop->withUrl($this->prop8InUrl);
     }
+
+    #[LiveProp(url: new UrlMapping('q'))]
+    public ?string $prop9 = null;
 }