feature #1507 [LiveComponent] Add modifier option to LiveProp (squrious)

This PR was squashed before being merged into the 2.x branch.

Discussion
----------

[LiveComponent] Add modifier option to LiveProp

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

Hi!

Following discussions in [#1396](#1396 (comment)), here is a proposal to allow a `LiveProp` to be modified at runtime.

The feature adds a `modifier` option to `LiveProp`, so users can use a custom method to modify the `LiveProp`'s options
depending on the context.

This context could be a service, or even another prop within the component.

### Usage

Here is the example given in the doc:

```php
#[AsLiveComponent]
class ProductSearch
{
    #[LiveProp(writable: true, modifier: 'modifyAddedDate')]
    public ?\DateTimeImmutable $addedDate;

    #[LiveProp]
    public string $dateFormat = 'Y-m-d';

    // ...

    public function modifyAddedDate(LiveProp $prop): LiveProp
    {
        return $prop->withFormat($this->dateFormat);
    }
}
```

```twig
{{ component('ProductSearch', {
    dateFormat: 'd/m/Y'
}) }}
```

### Changes overview

First, we have to make the `LiveProp` attribute editable in some way. I opted out for immutable methods, so caching is preserved when applicable.

Then add a `LivePropMetadata::withModifier(object $component)` method that returns a new instance modified by the user-defined method. This is called in a few places, similarly to `LiveComponentMetadata::calculateFieldName()`.

The tricky part is component hydration. If we use props in modifiers to change other `LiveProp` options, they have to be hydrated before the modifier is applied. This is only useful for options related to hydration, but it concerns most of them... The trick is to sort metadata, so modified ones are hydrated at the end.

Commits
-------

3bcc5c2 [LiveComponent] Add modifier option to LiveProp

Author: weaverryan

src/LiveComponent/CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## 2.17.0
+
+-   Add `modifier` option in `LiveProp` so options can be modified at runtime.
+
 ## 2.16.0
 
 -   LiveComponents is now stable and no longer experimental 🥳

src/LiveComponent/doc/index.rst

@@ -3450,6 +3450,53 @@ the change of one specific key::
         }
     }
 
+Set LiveProp Options Dynamically
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 2.17
+
+    The ``modifier`` option was added in LiveComponents 2.17.
+
+
+If you need to configure a LiveProp's options dynamically, you can use the ``modifier`` option to use a custom
+method in your component that returns a modified version of your LiveProp::
+
+
+    #[AsLiveComponent]
+    class ProductSearch
+    {
+        #[LiveProp(writable: true, modifier: 'modifyAddedDate')]
+        public ?\DateTimeImmutable $addedDate = null;
+
+        #[LiveProp]
+        public string $dateFormat = 'Y-m-d';
+
+        // ...
+
+        public function modifyAddedDate(LiveProp $prop): LiveProp
+        {
+            return $prop->withFormat($this->dateFormat);
+        }
+    }
+
+Then, when using your component in a template, you can change the date format used for ``$addedDate``:
+
+.. code-block:: twig
+
+    {{ component('ProductSearch', {
+        dateFormat: 'd/m/Y'
+    }) }}
+
+
+All ``LiveProp::with*`` methods are immutable, so you need to use their return value as your new LiveProp.
+
+.. caution::
+
+    Avoid relying on props that also use a modifier in other modifiers methods. For example, if the ``$dateFormat``
+    property above also had a ``modifier`` option, then it wouldn't be safe to reference it from the ``modifyAddedDate``
+    modifier method. This is because the ``$dateFormat`` property may not have been hydrated by this point.
+
+
 Debugging Components
 --------------------
 

src/LiveComponent/src/Attribute/LiveProp.php

@@ -101,10 +101,19 @@ public function __construct(
          * in the URL.
          */
         private bool $url = false,
+
+        /**
+         * A hook that will be called when this LiveProp is used.
+         *
+         * Allows to modify the LiveProp options depending on the context. The
+         * original LiveProp attribute instance will be passed as an argument to
+         * it.
+         *
+         * @var string|null
+         */
+        private string|null $modifier = null,
     ) {
-        if ($this->useSerializerForHydration && ($this->hydrateWith || $this->dehydrateWith)) {
-            throw new \InvalidArgumentException('Cannot use useSerializerForHydration with hydrateWith or dehydrateWith.');
-        }
+        self::validateHydrationStrategy($this);
     }
 
     /**
@@ -119,6 +128,14 @@ public function isIdentityWritable(): bool
         return \in_array(self::IDENTITY, $this->writable, true);
     }
 
+    public function withWritable(bool|array $writable): self
+    {
+        $clone = clone $this;
+        $clone->writable = $writable;
+
+        return $clone;
+    }
+
     /**
      * @internal
      */
@@ -141,6 +158,16 @@ public function hydrateMethod(): ?string
         return $this->hydrateWith ? trim($this->hydrateWith, '()') : null;
     }
 
+    public function withHydrateWith(?string $hydrateWith): self
+    {
+        $clone = clone $this;
+        $clone->hydrateWith = $hydrateWith;
+
+        self::validateHydrationStrategy($clone);
+
+        return $clone;
+    }
+
     /**
      * @internal
      */
@@ -149,6 +176,16 @@ public function dehydrateMethod(): ?string
         return $this->dehydrateWith ? trim($this->dehydrateWith, '()') : null;
     }
 
+    public function withDehydrateWith(?string $dehydrateWith): self
+    {
+        $clone = clone $this;
+        $clone->dehydrateWith = $dehydrateWith;
+
+        self::validateHydrationStrategy($clone);
+
+        return $clone;
+    }
+
     /**
      * @internal
      */
@@ -157,6 +194,16 @@ public function useSerializerForHydration(): bool
         return $this->useSerializerForHydration;
     }
 
+    public function withUseSerializerForHydration(bool $userSerializerForHydration): self
+    {
+        $clone = clone $this;
+        $clone->useSerializerForHydration = $userSerializerForHydration;
+
+        self::validateHydrationStrategy($clone);
+
+        return $clone;
+    }
+
     /**
      * @internal
      */
@@ -165,6 +212,16 @@ public function serializationContext(): array
         return $this->serializationContext;
     }
 
+    public function withSerializationContext(array $serializationContext): self
+    {
+        $clone = clone $this;
+        $clone->serializationContext = $serializationContext;
+
+        self::validateHydrationStrategy($clone);
+
+        return $clone;
+    }
+
     /**
      * @internal
      */
@@ -181,11 +238,27 @@ public function calculateFieldName(object $component, string $fallback): string
         return $this->fieldName;
     }
 
+    public function withFieldName(?string $fieldName): self
+    {
+        $clone = clone $this;
+        $clone->fieldName = $fieldName;
+
+        return $clone;
+    }
+
     public function format(): ?string
     {
         return $this->format;
     }
 
+    public function withFormat(?string $format): self
+    {
+        $clone = clone $this;
+        $clone->format = $format;
+
+        return $clone;
+    }
+
     public function acceptUpdatesFromParent(): bool
     {
         return $this->updateFromParent;
@@ -196,8 +269,36 @@ public function onUpdated(): string|array|null
         return $this->onUpdated;
     }
 
+    public function withOnUpdated(string|array|null $onUpdated): self
+    {
+        $clone = clone $this;
+        $clone->onUpdated = $onUpdated;
+
+        return $clone;
+    }
+
     public function url(): bool
     {
         return $this->url;
     }
+
+    public function withUrl(bool $url): self
+    {
+        $clone = clone $this;
+        $clone->url = $url;
+
+        return $clone;
+    }
+
+    public function modifier(): string|null
+    {
+        return $this->modifier;
+    }
+
+    private static function validateHydrationStrategy(self $liveProp): void
+    {
+        if ($liveProp->useSerializerForHydration && ($liveProp->hydrateWith || $liveProp->dehydrateWith)) {
+            throw new \InvalidArgumentException('Cannot use useSerializerForHydration with hydrateWith or dehydrateWith.');
+        }
+    }
 }

src/LiveComponent/src/DependencyInjection/LiveComponentExtension.php

@@ -227,6 +227,7 @@ function (ChildDefinition $definition, AsLiveComponent $attribute) {
                 new Reference('request_stack'),
                 new Reference('ux.live_component.metadata_factory'),
                 new Reference('ux.live_component.query_string_props_extractor'),
+                new Reference('property_accessor'),
             ])
             ->addTag('kernel.event_subscriber');
 

src/LiveComponent/src/EventListener/QueryStringInitializeSubscriber.php

@@ -13,9 +13,11 @@
 
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 use Symfony\Component\HttpFoundation\RequestStack;
+use Symfony\Component\PropertyAccess\Exception\ExceptionInterface as PropertyAccessExceptionInterface;
+use Symfony\Component\PropertyAccess\PropertyAccessorInterface;
 use Symfony\UX\LiveComponent\Metadata\LiveComponentMetadataFactory;
 use Symfony\UX\LiveComponent\Util\QueryStringPropsExtractor;
-use Symfony\UX\TwigComponent\Event\PreMountEvent;
+use Symfony\UX\TwigComponent\Event\PostMountEvent;
 
 /**
  * @author Nicolas Rigaud <[email protected]>
@@ -28,17 +30,18 @@ public function __construct(
         private readonly RequestStack $requestStack,
         private readonly LiveComponentMetadataFactory $metadataFactory,
         private readonly QueryStringPropsExtractor $queryStringPropsExtractor,
+        private readonly PropertyAccessorInterface $propertyAccessor,
     ) {
     }
 
     public static function getSubscribedEvents(): array
     {
         return [
-            PreMountEvent::class => 'onPreMount',
+            PostMountEvent::class => ['onPostMount', 256],
         ];
     }
 
-    public function onPreMount(PreMountEvent $event): void
+    public function onPostMount(PostMountEvent $event): void
     {
         if (!$event->getMetadata()->get('live', false)) {
             // Not a live component
@@ -53,12 +56,20 @@ public function onPreMount(PreMountEvent $event): void
 
         $metadata = $this->metadataFactory->getMetadata($event->getMetadata()->getName());
 
-        if (!$metadata->hasQueryStringBindings()) {
+        if (!$metadata->hasQueryStringBindings($event->getComponent())) {
             return;
         }
 
         $queryStringData = $this->queryStringPropsExtractor->extract($request, $metadata, $event->getComponent());
 
-        $event->setData(array_merge($event->getData(), $queryStringData));
+        $component = $event->getComponent();
+
+        foreach ($queryStringData as $name => $value) {
+            try {
+                $this->propertyAccessor->setValue($component, $name, $value);
+            } catch (PropertyAccessExceptionInterface $exception) {
+                // Ignore errors
+            }
+        }
     }
 }

src/LiveComponent/src/LiveComponentHydrator.php

@@ -63,7 +63,7 @@ public function dehydrate(object $component, ComponentAttributes $attributes, Li
         $takenFrontendPropertyNames = [];
 
         $dehydratedProps = new DehydratedProps();
-        foreach ($componentMetadata->getAllLivePropsMetadata() as $propMetadata) {
+        foreach ($componentMetadata->getAllLivePropsMetadata($component) as $propMetadata) {
             $propertyName = $propMetadata->getName();
             $frontendName = $propMetadata->calculateFieldName($component, $propertyName);
 
@@ -143,8 +143,9 @@ public function hydrate(object $component, array $props, array $updatedProps, Li
         $attributes = new ComponentAttributes($dehydratedOriginalProps->getPropValue(self::ATTRIBUTES_KEY, []));
         $dehydratedOriginalProps->removePropValue(self::ATTRIBUTES_KEY);
 
-        foreach ($componentMetadata->getAllLivePropsMetadata() as $propMetadata) {
+        foreach ($componentMetadata->getAllLivePropsMetadata($component) as $propMetadata) {
             $frontendName = $propMetadata->calculateFieldName($component, $propMetadata->getName());
+
             if (!$dehydratedOriginalProps->hasPropValue($frontendName)) {
                 // this property was not sent, so skip
                 // even if this has writable paths, if no identity is sent,

src/LiveComponent/src/Metadata/LiveComponentMetadata.php

@@ -25,6 +25,10 @@ public function __construct(
         /** @var LivePropMetadata[] */
         private array $livePropsMetadata,
     ) {
+        uasort(
+            $this->livePropsMetadata,
+            static fn (LivePropMetadata $a, LivePropMetadata $b) => $a->hasModifier() <=> $b->hasModifier()
+        );
     }
 
     public function getComponentMetadata(): ComponentMetadata
@@ -35,9 +39,11 @@ public function getComponentMetadata(): ComponentMetadata
     /**
      * @return LivePropMetadata[]
      */
-    public function getAllLivePropsMetadata(): array
+    public function getAllLivePropsMetadata(object $component): iterable
     {
-        return $this->livePropsMetadata;
+        foreach ($this->livePropsMetadata as $livePropMetadata) {
+            yield $livePropMetadata->withModifier($component);
+        }
     }
 
     /**
@@ -60,9 +66,9 @@ public function getOnlyPropsThatAcceptUpdatesFromParent(array $inputProps): arra
         return array_intersect_key($inputProps, array_flip($propNames));
     }
 
-    public function hasQueryStringBindings(): bool
+    public function hasQueryStringBindings($component): bool
     {
-        foreach ($this->getAllLivePropsMetadata() as $livePropMetadata) {
+        foreach ($this->getAllLivePropsMetadata($component) as $livePropMetadata) {
             if ($livePropMetadata->queryStringMapping()) {
                 return true;
             }

src/LiveComponent/src/Metadata/LiveComponentMetadataFactory.php

@@ -107,8 +107,7 @@ public function createLivePropMetadata(string $className, string $propertyName,
             $infoType,
             $isTypeBuiltIn,
             $isTypeNullable,
-            $collectionValueType,
-            $liveProp->url()
+            $collectionValueType
         );
     }