add PostMount component hook

Author: kbond

src/TwigComponent/CHANGELOG.md

@@ -6,6 +6,8 @@
 
 -   Add `PreMount` priority parameter.
 
+-   Add `PostMount` hook.
+
 ## 2.0.0
 
 -   Support for `stimulus` version 2 was removed and support for `@hotwired/stimulus`

src/TwigComponent/src/Attribute/AsTwigComponent.php

@@ -44,6 +44,17 @@ public static function preMountMethods(object $component): iterable
         return array_reverse($methods);
     }
 
+    public static function postMountMethods(object $component): iterable
+    {
+        $methods = iterator_to_array(self::attributeMethodsFor(PostMount::class, $component));
+
+        usort($methods, static function (\ReflectionMethod $a, \ReflectionMethod $b) {
+            return $a->getAttributes(PostMount::class)[0]->newInstance()->priority <=> $b->getAttributes(PostMount::class)[0]->newInstance()->priority;
+        });
+
+        return array_reverse($methods);
+    }
+
     /**
      * @internal
      *

src/TwigComponent/src/Attribute/PostMount.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace Symfony\UX\TwigComponent\Attribute;
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/**
+ * @author Kevin Bond <[email protected]>
+ *
+ * @experimental
+ */
+#[\Attribute(\Attribute::TARGET_METHOD)]
+final class PostMount
+{
+    public int $priority;
+
+    /**
+     * @param int $priority If multiple hooks are registered in a component, use to configure
+     *                      the order in which they are called (higher called earlier)
+     */
+    public function __construct(int $priority = 0)
+    {
+        $this->priority = $priority;
+    }
+}

src/TwigComponent/src/ComponentFactory.php

@@ -87,11 +87,17 @@ public function create(string $name, array $data = []): object
 
         // set data that wasn't set in mount on the component directly
         foreach ($data as $property => $value) {
-            if (!$this->propertyAccessor->isWritable($component, $property)) {
-                throw new \LogicException(sprintf('Unable to write "%s" to component "%s". Make sure this is a writable property or create a mount() with a $%s argument.', $property, \get_class($component), $property));
+            if ($this->propertyAccessor->isWritable($component, $property)) {
+                $this->propertyAccessor->setValue($component, $property, $value);
+
+                unset($data[$property]);
             }
+        }
+
+        $data = $this->postMount($component, $data);
 
-            $this->propertyAccessor->setValue($component, $property, $value);
+        foreach ($data as $property => $value) {
+            throw new \LogicException(sprintf('Unable to write "%s" to component "%s". Make sure this is a writable property or create a mount() with a $%s argument.', $property, \get_class($component), $property));
         }
 
         return $component;
@@ -151,4 +157,13 @@ private function preMount(object $component, array $data): array
 
         return $data;
     }
+
+    private function postMount(object $component, array $data): array
+    {
+        foreach (AsTwigComponent::postMountMethods($component) as $method) {
+            $data = $component->{$method->name}($data);
+        }
+
+        return $data;
+    }
 }

src/TwigComponent/src/Resources/doc/index.rst

@@ -264,6 +264,40 @@ component use a ``PreMount`` hook::
     the order in which they're called, use the ``priority`` attribute parameter:
     ``PreMount(priority: 10)`` (higher called earlier).
 
+PostMount Hook
+~~~~~~~~~~~~~~
+
+When a component is mounted with the passed data, if an item cannot be
+mounted on the component, an exception is thrown. You can intercept this
+behavior and "catch" this extra data with a ``PostMount`` hook method. This
+method accepts the extra data as an argument and must return an array. If
+the returned array is empty, the exception will be avoided::
+
+    // src/Components/AlertComponent.php
+
+    use Symfony\UX\TwigComponent\Attribute\PostMount;
+    // ...
+
+    #[AsTwigComponent('alert')]
+    class AlertComponent
+    {
+        #[PostMount]
+        public function postMount(array $data): array
+        {
+            // do something with the "extra" data
+
+            return $data;
+        }
+        // ...
+    }
+
+.. note::
+
+    If your component has multiple ``PostMount`` hooks, and you'd like to control
+    the order in which they're called, use the ``priority`` attribute parameter:
+    ``PostMount(priority: 10)`` (higher called earlier).
+>>>>>>> 0cd3131 (add `PostMount` component hook)
+
 Fetching Services
 -----------------
 

src/TwigComponent/tests/Fixture/Component/ComponentB.php

@@ -12,6 +12,7 @@
 namespace Symfony\UX\TwigComponent\Tests\Fixture\Component;
 
 use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;
+use Symfony\UX\TwigComponent\Attribute\PostMount;
 use Symfony\UX\TwigComponent\Attribute\PreMount;
 
 /**
@@ -21,6 +22,7 @@
 final class ComponentB
 {
     public string $value;
+    public string $postValue;
 
     #[PreMount]
     public function preMount(array $data): array
@@ -31,4 +33,12 @@ public function preMount(array $data): array
 
         return $data;
     }
+
+    #[PostMount]
+    public function postMount(array $data): array
+    {
+        $this->postValue = $data['extra'] ?? 'default';
+
+        return [];
+    }
 }

src/TwigComponent/tests/Fixture/templates/components/custom1.html.twig

@@ -1,2 +1,3 @@
 Custom template 1
 b value: {{ value }}
+post value: {{ postValue }}

src/TwigComponent/tests/Fixture/templates/template_b.html.twig

@@ -1,3 +1,3 @@
 {{ component('component_a', { propA: 'prop a value 1', propB: 'prop b value 1' }) }}
 {{ component('component_a', { propA: 'prop a value 2', propB: 'prop b value 2' }) }}
-{{ component('component_b', { value: 'b value 1' }) }}
+{{ component('component_b', { value: 'b value 1', extra: 'value' }) }}

src/TwigComponent/tests/Integration/ComponentExtensionTest.php

@@ -39,6 +39,7 @@ public function testCanRenderTheSameComponentMultipleTimes(): void
         $this->assertStringContainsString('propA: prop a value 2', $output);
         $this->assertStringContainsString('propB: prop b value 2', $output);
         $this->assertStringContainsString('b value: pre-mount b value 1', $output);
+        $this->assertStringContainsString('post value: value', $output);
         $this->assertStringContainsString('service: service a value', $output);
     }
 

src/TwigComponent/tests/Unit/Attribute/AsTwigComponentTest.php

@@ -13,6 +13,7 @@
 
 use PHPUnit\Framework\TestCase;
 use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;
+use Symfony\UX\TwigComponent\Attribute\PostMount;
 use Symfony\UX\TwigComponent\Attribute\PreMount;
 
 /**
@@ -46,4 +47,31 @@ public function hook3()
         $this->assertSame('hook3', $hooks[1]->name);
         $this->assertSame('hook1', $hooks[2]->name);
     }
+
+    public function testPostMountHooksAreOrderedByPriority(): void
+    {
+        $hooks = AsTwigComponent::postMountMethods(
+            new class() {
+                #[PostMount(priority: -10)]
+                public function hook1()
+                {
+                }
+
+                #[PostMount(priority: 10)]
+                public function hook2()
+                {
+                }
+
+                #[PostMount]
+                public function hook3()
+                {
+                }
+            }
+        );
+
+        $this->assertCount(3, $hooks);
+        $this->assertSame('hook2', $hooks[0]->name);
+        $this->assertSame('hook3', $hooks[1]->name);
+        $this->assertSame('hook1', $hooks[2]->name);
+    }
 }