[LiveComponent] Alias URL bound props

[squrious]

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

Following https://github.com/symfony/ux/pull/1230.

Allow custom parameter names for URL bound props, and mapping specification from Twig templates.

Usage

From PHP definition:

#[AsLiveComponent()]
final class MyComponent
{
    // ...

    #[LiveProp(writable: true, url: new QueryMapping(alias: 'q'))
    public ?string $search = null;
}

From templates:

{{ component('MyComponent', {
     'data-live-url-mapping-search': {
       'alias': 'q'
      }
   }) 
}}
{{ component('MyComponent', { 'data-live-url-mapping-search-alias': 'q' }) }}

HTML syntax also works:

<twig:MyComponent :data-live-url-mapping-search="{ alias: 'q'}" />
<twig:MyComponent data-live-url-mapping-search-alias="q" />

Result

Changing the value of search will update the url to https://my.domain?q=my+search+string.

Mappings provided in Twig templates are merged into those provided in PHP. Thus, query mappings in PHP act as defaults, and we can override them in templates (e.g. for specific page requirements). So a page with:

<twig:MyComponent/>
<twig:MyComponent data-live-url-mapping-search-alias="q" />

will update its URL to http://my.domain?search=foo&q=bar.

[smnandre]

Is it accessible in PHP easily ?

[squrious]

Is it accessible in PHP easily ?

It's in the LiveProp metadata, so yes

[weaverryan]

Thanks for this!

What's the use-case for needing to do:

data-live-url-mapping-search-alias="q"

This doesn't look like something that Livewire has (I check there as a quick way to validate the value of features).

Also: QueryMapping(alias: 'q') or QueryMapping(as: 'q')? as stolen from Livewire :p

[smnandre]

Is it accessible in PHP easily ?

It's in the LiveProp metadata, so yes

But... it's on a call per call basis... so a call to metadataFactory would not bring this data right ? So it's not usable in events, cache, etc ?

(just want to clarify when/where this data will be exposed, accessible, etc)

[smnandre]

I'm not sure to understand how the live prop mapping is "kept" during live action / event.. but it's probably just me needing coffee..

[squrious]

@weaverryan

What's the use-case for needing to do:

data-live-url-mapping-search-alias="q"

If the users just want to override this mapping property they can do it with this shortened syntax instead of passing an object. It may also be useful in the future when the mapping object contain other options: it will be easier to conditionally render specific attributes in this way, than setting up an object, IMO.

This doesn't look like something that Livewire has (I check there as a quick way to validate the value of features).

That's true, but I tried the Livewire feature, and honestly I missed it. As far I know, you can't avoid parameter name collision in Livewire, but I find it pretty useful.

Also: QueryMapping(alias: 'q') or QueryMapping(as: 'q')? as stolen from Livewire :p

I'm totally open for any renaming :) as looks good to me!

@smandre

But... it's on a call per call basis... so a call to metadataFactory would not bring this data right ? So it's not usable in events, cache, etc ?

The metadata defined in your PHP component is available through the metadata factory. If you override the mapping in a template, the overridden values will not be available from metadata. Though there is a utility class that helps in getting those values from mounted attributes.

I'm not sure to understand how the live prop mapping is "kept" during live action / event.. but it's probably just me needing coffee..

The mapping is render as a Stimulus value here.

[smnandre]

I'm still not sure if i'm paranoiac ... but if you're telling me that the "mapping configuration" is read and used from request data ...

I'm 90% sure i still miss something so i stop here :)

[squrious]

I renamed QueryMapping to UrlMapping, alias to as, and rebased to add some doc on this feature :)

[squrious]

Hi there!

Just rebased to get the LiveProp modifier feature.

I also rewrote the test component for url bindings. We often add use cases and I found it becomes hard to understand things like "prop1", "prop2", etc in assertions. This is in a separate commit, so if it's not the best place do do this it can be removed easily ;)

Doc section is also updated!

[smnandre]

@squrious where are we here ? Do you need something / is it "ready" for you ?

[squrious]

@squrious where are we here ? Do you need something / is it "ready" for you ?

Hi @smnandre! It's ready for me

[kbond]

Thanks Nicolas for your time and patience on this!