Add modifier option to LiveProp

Author: squrious

src/LiveComponent/CHANGELOG.md

@@ -7,6 +7,7 @@
     new morphing library in 2.14.0 #1484
 -   Fix bug where the active input would maintain its value, but lose its cursor position #1501
 -   Restrict Twig 3.9 for now #1486
+-   Add `modifier` option in `LiveProp` so options can be modified at runtime.
 
 ## 2.14.1
 

src/LiveComponent/doc/index.rst

@@ -3348,6 +3348,52 @@ the change of one specific key::
         }
     }
 
+Set LiveProp Options Dynamically
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 2.15
+
+    The ``modifier`` option was added in LiveComponents 2.15.
+
+
+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;
+
+        #[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::
+
+    You must not rely on props that also use a modifier in other modifiers methods, as their modifiers will not
+    necessarily be applied in the correct order when hydrating components.
+
+
 Debugging Components
 --------------------
 

src/LiveComponent/src/Attribute/LiveProp.php

@@ -103,10 +103,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);
     }
 
     /**
@@ -121,6 +130,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
      */
@@ -143,6 +160,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
      */
@@ -151,6 +178,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
      */
@@ -159,6 +196,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
      */
@@ -167,6 +214,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
      */
@@ -183,11 +240,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;
@@ -198,8 +271,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/LiveComponentHydrator.php

@@ -66,6 +66,7 @@ public function dehydrate(object $component, ComponentAttributes $attributes, Li
 
         $dehydratedProps = new DehydratedProps();
         foreach ($componentMetadata->getAllLivePropsMetadata() as $propMetadata) {
+            $propMetadata = $propMetadata->withModifier($component);
             $propertyName = $propMetadata->getName();
             $frontendName = $propMetadata->calculateFieldName($component, $propertyName);
 
@@ -145,7 +146,20 @@ 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) {
+        $allMetadata = $componentMetadata->getAllLivePropsMetadata();
+        uasort($allMetadata, static function (LivePropMetadata $a, LivePropMetadata $b) {
+            if ($a->hasModifier() && !$b->hasModifier()) {
+                return 1;
+            } elseif (!$a->hasModifier() && $b->hasModifier()) {
+                return -1;
+            } else {
+                return 0;
+            }
+        });
+
+        foreach ($allMetadata as $propMetadata) {
+            $propMetadata = $propMetadata->withModifier($component);
+            //        foreach ($componentMetadata->getAllLivePropsMetadata($component) as $propMetadata) {
             $frontendName = $propMetadata->calculateFieldName($component, $propMetadata->getName());
             if (!$dehydratedOriginalProps->hasPropValue($frontendName)) {
                 // this property was not sent, so skip

src/LiveComponent/src/Metadata/LiveComponentMetadataFactory.php

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

src/LiveComponent/src/Metadata/LivePropMetadata.php

@@ -30,7 +30,6 @@ public function __construct(
         private bool $isBuiltIn,
         private bool $allowsNull,
         private ?Type $collectionValueType,
-        private bool $queryStringMapping,
     ) {
     }
 
@@ -56,7 +55,7 @@ public function allowsNull(): bool
 
     public function queryStringMapping(): bool
     {
-        return $this->queryStringMapping;
+        return $this->liveProp->url();
     }
 
     public function calculateFieldName(object $component, string $fallback): string
@@ -116,4 +115,36 @@ public function onUpdated(): string|array|null
     {
         return $this->liveProp->onUpdated();
     }
+
+    public function hasModifier(): bool
+    {
+        return null !== $this->liveProp->modifier();
+    }
+
+    /**
+     * Applies a modifier specified in LiveProp attribute.
+     *
+     * If a modifier is specified, a modified clone is returned.
+     * Otherwise, the metadata is returned as it is.
+     */
+    public function withModifier(object $component): self
+    {
+        if (null === ($modifier = $this->liveProp->modifier())) {
+            return $this;
+        }
+
+        if (!method_exists($component, $modifier)) {
+            throw new \LogicException(sprintf('Method "%s::%s()" given in LiveProp "modifier" does not exist.', $component::class, $modifier));
+        }
+
+        $modifiedLiveProp = $component->{$modifier}($this->liveProp);
+        if (!$modifiedLiveProp instanceof LiveProp) {
+            throw new \LogicException(sprintf('Method "%s::%s()" should return an instance of "%s" (given: "%s").', $component::class, $modifier, LiveProp::class, get_debug_type($modifiedLiveProp)));
+        }
+
+        $clone = clone $this;
+        $clone->liveProp = $modifiedLiveProp;
+
+        return $clone;
+    }
 }

src/LiveComponent/src/Util/LiveControllerAttributesCreator.php

@@ -108,6 +108,7 @@ public function attributesForRendering(MountedComponent $mounted, ComponentMetad
         if ($liveMetadata->hasQueryStringBindings()) {
             $queryMapping = [];
             foreach ($liveMetadata->getAllLivePropsMetadata() as $livePropMetadata) {
+                $livePropMetadata = $livePropMetadata->withModifier($mounted->getComponent());
                 if ($livePropMetadata->queryStringMapping()) {
                     $frontendName = $livePropMetadata->calculateFieldName($mounted, $livePropMetadata->getName());
                     $queryMapping[$frontendName] = ['name' => $frontendName];

src/LiveComponent/src/Util/QueryStringPropsExtractor.php

@@ -43,6 +43,7 @@ public function extract(Request $request, LiveComponentMetadata $metadata, objec
         $data = [];
 
         foreach ($metadata->getAllLivePropsMetadata() as $livePropMetadata) {
+            $livePropMetadata = $livePropMetadata->withModifier($component);
             if ($livePropMetadata->queryStringMapping()) {
                 $frontendName = $livePropMetadata->calculateFieldName($component, $livePropMetadata->getName());
                 if (null !== ($value = $query[$frontendName] ?? null)) {

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

@@ -38,4 +38,15 @@ class ComponentWithUrlBoundProps
 
     #[LiveProp(fieldName: 'field6', url: true)]
     public ?string $prop6 = null;
+
+    #[LiveProp(modifier: 'modifyProp7')]
+    public ?string $prop7 = null;
+
+    #[LiveProp]
+    public ?bool $prop7InUrl = false;
+
+    public function modifyProp7(LiveProp $prop): LiveProp
+    {
+        return $prop->withUrl(true);
+    }
 }

src/LiveComponent/tests/Fixtures/templates/components/component_with_url_bound_props.html.twig

@@ -5,4 +5,5 @@
     Prop4: {{ prop4 }}
     Prop5: address: {{ prop5.address ?? '' }} city: {{ prop5.city ?? '' }}
     Prop6: {{ prop6 }}
-</div>
+    Prop7: {{ prop7 }}
+</div>

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

@@ -151,6 +151,7 @@ public function testQueryStringMappingAttribute()
             'prop3' => ['name' => 'prop3'],
             'prop5' => ['name' => 'prop5'],
             'field6' => ['name' => 'field6'],
+            'prop7' => ['name' => 'prop7'],
         ];
 
         $this->assertEquals($expected, $queryMapping);

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

@@ -21,14 +21,15 @@ class QueryStringInitializerSubscriberTest extends KernelTestCase
     public function testQueryStringPropsInitialization()
     {
         $this->browser()
-            ->get('/render-template/render_component_with_url_bound_props?prop1=foo&prop2=42&prop3[]=foo&prop3[]=bar&prop4=unbound&prop5[address]=foo&prop5[city]=bar&field6=foo')
+            ->get('/render-template/render_component_with_url_bound_props?prop1=foo&prop2=42&prop3[]=foo&prop3[]=bar&prop4=unbound&prop5[address]=foo&prop5[city]=bar&field6=foo&prop7=foo')
             ->assertSuccessful()
             ->assertContains('Prop1: foo')
             ->assertContains('Prop2: 42')
             ->assertContains('Prop3: foo,bar')
             ->assertContains('Prop4:')
             ->assertContains('Prop5: address: foo city: bar')
             ->assertContains('Prop6: foo')
+            ->assertContains('Prop7: foo')
         ;
     }
 }