[LiveComponents] OnUpdate hook for LiveProp

Author: bocharsky-bw

src/LiveComponent/CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## 2.12.0
+
+-   Add `onUpdated` hook for `LiveProp`
+
 ## 2.11.0
 
 -   Add helper for testing live components.

src/LiveComponent/doc/index.rst

@@ -3063,6 +3063,62 @@ Then specify this new route on your component:
           use DefaultActionTrait;
       }
 
+Add a Hook on LiveProp Update
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 2.12
+
+    The ``onUpdated`` option was added in LiveComponents 2.12.
+
+If you want to run custom code after a specific LiveProp is updated,
+you can do it by adding an ``onUpdated`` option set to a public method name
+on the component:
+
+.. code-block:: diff
+
+    // ...
+
+    #[AsLiveComponent]
+    class ProductSearch
+    {
+      - #[LiveProp(writable: true)]
+      + #[LiveProp(writable: true, onUpdated: 'onQueryUpdated')]
+        public string $query = '';
+
+        // ...
+
+        public function onQueryUpdated($previousValue): void
+        {
+            // $this->query already contains a new value
+            // and its previous value is passed as an argument
+        }
+    }
+}
+
+As soon as the `query` LiveProp is updated, the ``onQueryUpdated()`` method
+will be called. The previous value is passed there as the first argument.
+
+If you're allowing object properties to be writable, you can also listen to
+the change of one specific key:
+
+.. code-block::
+
+    // ...
+
+    #[AsLiveComponent]
+    class EditPost
+    {
+        #[LiveProp(writable: ['title', 'content'], onUpdated: ['title' => 'onTitleUpdated'])]
+        public Post $post;
+
+        // ...
+
+        public function onTitleUpdated($previousValue): void
+        {
+            // ...
+        }
+    }
+
 Test Helper
 -----------
 

src/LiveComponent/src/Attribute/LiveProp.php

@@ -49,6 +49,15 @@ final class LiveProp
 
     private bool $acceptUpdatesFromParent;
 
+    /**
+     * @var string|string[]|null
+     *
+     * A hook that will be called after the property is updated.
+     * Set it to a method name on the Live Component that should be called.
+     * The old value of the property will be passed as an argument to it.
+     */
+    private null|string|array $onUpdated;
+
     /**
      * @param bool|array  $writable                  If true, this property can be changed by the frontend.
      *                                               Or set to an array of paths within this object/array
@@ -73,7 +82,8 @@ public function __construct(
         array $serializationContext = [],
         string $fieldName = null,
         string $format = null,
-        bool $updateFromParent = false
+        bool $updateFromParent = false,
+        string|array $onUpdated = null,
     ) {
         $this->writable = $writable;
         $this->hydrateWith = $hydrateWith;
@@ -83,6 +93,7 @@ public function __construct(
         $this->fieldName = $fieldName;
         $this->format = $format;
         $this->acceptUpdatesFromParent = $updateFromParent;
+        $this->onUpdated = $onUpdated;
 
         if ($this->useSerializerForHydration && ($this->hydrateWith || $this->dehydrateWith)) {
             throw new \InvalidArgumentException('Cannot use useSerializerForHydration with hydrateWith or dehydrateWith.');
@@ -172,4 +183,9 @@ public function acceptUpdatesFromParent(): bool
     {
         return $this->acceptUpdatesFromParent;
     }
+
+    public function onUpdated(): null|string|array
+    {
+        return $this->onUpdated;
+    }
 }

src/LiveComponent/src/LiveComponentHydrator.php

@@ -20,6 +20,7 @@
 use Symfony\Component\Serializer\Normalizer\DenormalizerInterface;
 use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
 use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
+use Symfony\UX\LiveComponent\Attribute\LiveProp;
 use Symfony\UX\LiveComponent\Exception\HydrationException;
 use Symfony\UX\LiveComponent\Hydration\HydrationExtensionInterface;
 use Symfony\UX\LiveComponent\Metadata\LiveComponentMetadata;
@@ -208,6 +209,10 @@ public function hydrate(object $component, array $props, array $updatedProps, Li
                 // unexpected and can't be set - e.g. a string field for an `int` property.
                 // We ignore this, and allow the original value to remain set.
             }
+
+            if ($propMetadata->onUpdated()) {
+                $this->processOnUpdatedHook($component, $frontendName, $propMetadata, $dehydratedUpdatedProps, $dehydratedOriginalProps);
+            }
         }
 
         foreach (AsLiveComponent::postHydrateMethods($component) as $method) {
@@ -559,4 +564,52 @@ private function recursiveKeySort(array &$data): void
         }
         ksort($data);
     }
+
+    private function ensureOnUpdatedMethodExists(object $component, string $methodName): void
+    {
+        if (method_exists($component, $methodName)) {
+            return;
+        }
+
+        throw new \Exception(sprintf('Method "%s:%s()" specified as LiveProp "onUpdated" hook does not exist.', $component::class, $methodName));
+    }
+
+    /**
+     * A special hook that will be called if the LiveProp was changed
+     * and $onUpdated argument is set on its attribute.
+     */
+    private function processOnUpdatedHook(object $component, string $frontendName, LivePropMetadata $propMetadata, DehydratedProps $dehydratedUpdatedProps, DehydratedProps $dehydratedOriginalProps): void
+    {
+        $onUpdated = $propMetadata->onUpdated();
+        if (\is_string($onUpdated)) {
+            $onUpdated = [LiveProp::IDENTITY => $onUpdated];
+        }
+
+        foreach ($onUpdated as $propName => $funcName) {
+            if (LiveProp::IDENTITY === $propName) {
+                if (!$dehydratedUpdatedProps->hasPropValue($frontendName)) {
+                    continue;
+                }
+
+                $this->ensureOnUpdatedMethodExists($component, $funcName);
+                $propertyOldValue = $this->hydrateValue(
+                    $dehydratedOriginalProps->getPropValue($frontendName),
+                    $propMetadata,
+                    $component,
+                );
+                $component->{$funcName}($propertyOldValue);
+
+                continue;
+            }
+
+            $key = sprintf('%s.%s', $frontendName, $propName);
+            if (!$dehydratedUpdatedProps->hasPropValue($key)) {
+                continue;
+            }
+
+            $this->ensureOnUpdatedMethodExists($component, $funcName);
+            $propertyOldValue = $dehydratedOriginalProps->getPropValue($key);
+            $component->{$funcName}($propertyOldValue);
+        }
+    }
 }

src/LiveComponent/src/Metadata/LivePropMetadata.php

@@ -105,4 +105,9 @@ public function getFormat(): ?string
     {
         return $this->liveProp->format();
     }
+
+    public function onUpdated(): null|string|array
+    {
+        return $this->liveProp->onUpdated();
+    }
 }

src/LiveComponent/tests/Integration/LiveComponentHydratorTest.php

@@ -144,6 +144,90 @@ public function testCanDehydrateAndHydrateComponentWithTestCases(callable $testF
 
     public function provideDehydrationHydrationTests(): iterable
     {
+        yield 'onUpdated: exception if method not exists' => [function () {
+            return HydrationTest::create(new class() {
+                #[LiveProp(writable: true, onUpdated: 'onFirstNameUpdated')]
+                public string $firstName;
+            })
+                ->mountWith(['firstName' => 'Ryan'])
+                ->userUpdatesProps(['firstName' => 'Victor'])
+                ->expectsExceptionDuringHydration(\Exception::class, '/onFirstNameUpdated\(\)" specified as LiveProp "onUpdated" hook does not exist/');
+        }];
+
+        yield 'onUpdated: with scalar value' => [function () {
+            return HydrationTest::create(new class() {
+                #[LiveProp(writable: true, onUpdated: 'onFirstNameUpdated')]
+                public string $firstName;
+
+                public function onFirstNameUpdated($oldValue)
+                {
+                    if ('Victor' === $this->firstName) {
+                        $this->firstName = 'Revert to '.$oldValue;
+                    }
+                }
+            })
+                ->mountWith(['firstName' => 'Ryan'])
+                ->userUpdatesProps(['firstName' => 'Victor'])
+                ->assertObjectAfterHydration(function (object $object) {
+                    $this->assertSame('Revert to Ryan', $object->firstName);
+                });
+        }];
+
+        yield 'onUpdated: set to an array' => [function () {
+            $product = create(ProductFixtureEntity::class, [
+                'name' => 'Chicken',
+            ])->object();
+
+            return HydrationTest::create(new class() {
+                #[LiveProp(writable: ['name'], onUpdated: ['name' => 'onNameUpdated'])]
+                public ProductFixtureEntity $product;
+
+                public function onNameUpdated($oldValue)
+                {
+                    if ('Rabbit' === $this->product->name) {
+                        $this->product->name = 'Revert to '.$oldValue;
+                    }
+                }
+            })
+                ->mountWith(['product' => $product])
+                ->userUpdatesProps(['product.name' => 'Rabbit'])
+                ->assertObjectAfterHydration(function (object $object) {
+                    $this->assertSame('Revert to Chicken', $object->product->name);
+                });
+        }];
+
+        yield 'onUpdated: with IDENTITY' => [function () {
+            $entityOriginal = create(Entity1::class)->object();
+            $entityNext = create(Entity1::class)->object();
+            \assert($entityOriginal instanceof Entity1);
+            \assert($entityNext instanceof Entity1);
+
+            return HydrationTest::create(new class() {
+                #[LiveProp(writable: [LiveProp::IDENTITY], onUpdated: [LiveProp::IDENTITY => 'onEntireEntityUpdated'])]
+                public Entity1 $entity1;
+
+                public function onEntireEntityUpdated($oldValue)
+                {
+                    // Sanity check
+                    if ($this->entity1 === $oldValue) {
+                        throw new \Exception('Old value is the same entity?!');
+                    }
+                    if (2 === $this->entity1->id) {
+                        // Revert the value
+                        $this->entity1 = $oldValue;
+                    }
+                }
+            })
+                ->mountWith(['entity1' => $entityOriginal])
+                ->userUpdatesProps(['entity1' => $entityNext->id])
+                ->assertObjectAfterHydration(function (object $object) use ($entityOriginal) {
+                    $this->assertSame(
+                        $entityOriginal->id,
+                        $object->entity1->id
+                    );
+                });
+        }];
+
         yield 'string: (de)hydrates correctly' => [function () {
             return HydrationTest::create(new class() {
                 #[LiveProp()]

src/Turbo/tests/app/Kernel.php

@@ -291,7 +291,7 @@ public function artistFromSong(Request $request, EntityManagerInterface $doctrin
                 if (!$artist) {
                     throw new NotFoundHttpException();
                 }
-                $artist->name = $artist->name.' after change';
+                $artist->name .= ' after change';
 
                 $doctrine->flush();
             }