Merge branch '2.x' into add-component-debug-command

Author: StevenRenaux

.github/workflows/doctor-rst.yaml

@@ -16,7 +16,7 @@ jobs:
               run: mkdir .cache
 
             - name: Extract base branch name
-              run: echo "##[set-output name=branch;]$(echo ${GITHUB_BASE_REF:=${GITHUB_REF##*/}})"
+              run: echo "branch=$(echo ${GITHUB_BASE_REF:=${GITHUB_REF##*/}})" >> $GITHUB_OUTPUT
               id: extract_base_branch
 
             - name: Cache DOCtor-RST

.github/workflows/test-turbo.yml

@@ -9,7 +9,7 @@ jobs:
         runs-on: ubuntu-latest
         steps:
             -   name: Checkout
-                uses: actions/checkout@v2
+                uses: actions/checkout@v3
 
             - name: Setup PHP
               uses: shivammathur/setup-php@v2
@@ -52,7 +52,7 @@ jobs:
 
         steps:
             - name: Checkout
-              uses: actions/checkout@v2
+              uses: actions/checkout@v3
 
             - name: Setup PHP
               uses: shivammathur/setup-php@v2
@@ -69,7 +69,7 @@ jobs:
               id: yarn-cache-dir-path
               run: echo "dir=$(yarn cache dir)" >> $GITHUB_OUTPUT
 
-            - uses: actions/cache@v2
+            - uses: actions/cache@v3
               id: yarn-cache
               with:
                   path: ${{ steps.yarn-cache-dir-path.outputs.dir }}

.github/workflows/test.yaml

@@ -8,7 +8,7 @@ jobs:
     coding-style-php:
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@master
+            - uses: actions/checkout@v3
             - uses: shivammathur/setup-php@v2
               with:
                   php-version: '8.1'
@@ -20,11 +20,11 @@ jobs:
         name: JavaScript Coding Style
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@master
+            - uses: actions/checkout@v3
             - name: Get yarn cache directory path
               id: yarn-cache-dir-path
               run: echo "dir=$(yarn cache dir)" >> $GITHUB_OUTPUT
-            - uses: actions/cache@v2
+            - uses: actions/cache@v3
               id: yarn-cache
               with:
                   path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
@@ -39,11 +39,11 @@ jobs:
         name: Check for UnBuilt JS Dist Files
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@master
+            - uses: actions/checkout@v3
             - name: Get yarn cache directory path
               id: yarn-cache-dir-path
               run: echo "dir=$(yarn cache dir)" >> $GITHUB_OUTPUT
-            - uses: actions/cache@v2
+            - uses: actions/cache@v3
               id: yarn-cache
               with:
                   path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
@@ -124,11 +124,11 @@ jobs:
     tests-js:
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@master
+            - uses: actions/checkout@v3
             - name: Get yarn cache directory path
               id: yarn-cache-dir-path
               run: echo "dir=$(yarn cache dir)" >> $GITHUB_OUTPUT
-            - uses: actions/cache@v2
+            - uses: actions/cache@v3
               id: yarn-cache
               with:
                   path: ${{ steps.yarn-cache-dir-path.outputs.dir }}

src/Autocomplete/tests/Functional/AutocompleteFormRenderingTest.php

@@ -63,8 +63,6 @@ public function testCategoryFieldSubmitsCorrectly()
             // the option does NOT match something returned by query_builder
             // so ONLY the placeholder shows up
             ->assertElementCount('#product_category_autocomplete option', 1)
-            ->assertNotContains('First cat')
-
             ->assertNotContains('First cat')
             ->post('/test-form', [
                 'body' => [

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

@@ -1158,9 +1158,9 @@ shortcuts. We even added a flash message!
 Uploading files
 ---------------
 
-.. versionadded:: 2.9
+.. versionadded:: 2.11
 
-    The ability to upload files to actions was added in version 2.9.
+    The ability to upload files to actions was added in version 2.11.
 
 Files aren't sent to the component by default. You need to use a live action
 to handle the files and tell the component when the file should be sent:
@@ -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
+        {
+            // ...
+        }
+    }
+
 Debugging Components
 --------------------
 
@@ -3129,6 +3185,20 @@ uses Symfony's test client to render and make requests to your components::
             $response = $testComponent->call('redirect')->response(); // Symfony\Component\HttpFoundation\Response
 
             $this->assertSame(302, $response->getStatusCode());
+
+            // authenticate a user ($user is instance of UserInterface)
+            $testComponent->actingAs($user);
+
+            // customize the test client
+            $client = self::getContainer()->get('test.client');
+
+            // do some stuff with the client (ie login user via form)
+
+            $testComponent = $this->createLiveComponent(
+                name: 'MyComponent',
+                data: ['foo' => 'bar'],
+                client: $client,
+            );
         }
     }
 

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/src/Test/InteractsWithLiveComponents.php

@@ -11,6 +11,7 @@
 
 namespace Symfony\UX\LiveComponent\Test;
 
+use Symfony\Bundle\FrameworkBundle\KernelBrowser;
 use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
 use Symfony\UX\TwigComponent\ComponentFactory;
 
@@ -19,7 +20,7 @@
  */
 trait InteractsWithLiveComponents
 {
-    protected function createLiveComponent(string $name, array $data = []): TestLiveComponent
+    protected function createLiveComponent(string $name, array $data = [], KernelBrowser $client = null): TestLiveComponent
     {
         if (!$this instanceof KernelTestCase) {
             throw new \LogicException(sprintf('The "%s" trait can only be used on "%s" classes.', __TRAIT__, KernelTestCase::class));
@@ -37,7 +38,7 @@ protected function createLiveComponent(string $name, array $data = []): TestLive
             $metadata,
             $data,
             $factory,
-            self::getContainer()->get('test.client'),
+            $client ?? self::getContainer()->get('test.client'),
             self::getContainer()->get('ux.live_component.component_hydrator'),
             self::getContainer()->get('ux.live_component.metadata_factory'),
             self::getContainer()->get('router'),