feature #189 [TwigComponent] add PreMount hook (kbond)

This PR was merged into the 2.x branch.

Discussion
----------

[TwigComponent] add `PreMount` hook

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| Tickets       | Fix #142
| License       | MIT

Commits
-------

9913151 [TwigComponent] add PreMount attribute/hook (closes #142)

Author: weaverryan

src/LiveComponent/src/Attribute/AsLiveComponent.php

@@ -99,20 +99,6 @@ public static function preDehydrateMethods(object $component): \Traversable
         yield from self::attributeMethodsFor(PreDehydrate::class, $component);
     }
 
-    /**
-     * @param string|object $classOrObject
-     *
-     * @return \ReflectionMethod[]
-     */
-    private static function attributeMethodsFor(string $attribute, object $component): \Traversable
-    {
-        foreach ((new \ReflectionClass($component))->getMethods(\ReflectionMethod::IS_PUBLIC) as $method) {
-            if ($method->getAttributes($attribute)[0] ?? null) {
-                yield $method;
-            }
-        }
-    }
-
     /**
      * @return \ReflectionProperty[]
      */

src/TwigComponent/README.md

@@ -217,6 +217,40 @@ If an option name matches an argument name in `mount()`, the
 option is passed as that argument and the component system
 will _not_ try to set it directly on a property.
 
+### PreMount Hook
+
+If you need to modify/validate data before it's _mounted_ on the
+component use a `PreMount` hook:
+
+```php
+// src/Components/AlertComponent.php
+
+use Symfony\UX\TwigComponent\Attribute\PreMount;
+// ...
+
+#[AsTwigComponent('alert')]
+class AlertComponent
+{
+    public string $message;
+    public string $type = 'success';
+
+    #[PreMount]
+    public function preMount(array $data): array
+    {
+        // validate data
+        $resolver = new OptionsResolver();
+        $resolver->setDefaults(['type' => 'success']);
+        $resolver->setAllowedValues('type', ['success', 'danger']);
+        $resolver->setRequired('message');
+        $resolver->setAllowedTypes('message', 'string');
+
+        return $resolver->resolve($data)
+    }
+
+    // ...
+}
+```
+
 ## Fetching Services
 
 Let's create a more complex example: a "featured products" component.

src/TwigComponent/src/Attribute/AsTwigComponent.php

@@ -27,4 +27,28 @@ public function __construct(string $name, ?string $template = null)
         $this->name = $name;
         $this->template = $template;
     }
+
+    /**
+     * @internal
+     *
+     * @return \ReflectionMethod[]
+     */
+    public static function preMountMethods(object $component): \Traversable
+    {
+        yield from self::attributeMethodsFor(PreMount::class, $component);
+    }
+
+    /**
+     * @internal
+     *
+     * @return \ReflectionMethod[]
+     */
+    protected static function attributeMethodsFor(string $attribute, object $component): \Traversable
+    {
+        foreach ((new \ReflectionClass($component))->getMethods(\ReflectionMethod::IS_PUBLIC) as $method) {
+            if ($method->getAttributes($attribute)[0] ?? null) {
+                yield $method;
+            }
+        }
+    }
 }

src/TwigComponent/src/Attribute/PreMount.php

@@ -0,0 +1,22 @@
+<?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 PreMount
+{
+}

src/TwigComponent/src/ComponentFactory.php

@@ -13,6 +13,7 @@
 
 use Symfony\Component\DependencyInjection\ServiceLocator;
 use Symfony\Component\PropertyAccess\PropertyAccessorInterface;
+use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;
 
 /**
  * @author Kevin Bond <[email protected]>
@@ -80,6 +81,7 @@ public function configFor($component, string $name = null): array
     public function create(string $name, array $data = []): object
     {
         $component = $this->getComponent($name);
+        $data = $this->preMount($component, $data);
 
         $this->mount($component, $data);
 
@@ -140,4 +142,13 @@ private function getComponent(string $name): object
 
         return $this->components->get($name);
     }
+
+    private function preMount(object $component, array $data): array
+    {
+        foreach (AsTwigComponent::preMountMethods($component) as $method) {
+            $data = $component->{$method->name}($data);
+        }
+
+        return $data;
+    }
 }

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

@@ -12,11 +12,23 @@
 namespace Symfony\UX\TwigComponent\Tests\Fixture\Component;
 
 use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;
+use Symfony\UX\TwigComponent\Attribute\PreMount;
 
 /**
  * @author Kevin Bond <[email protected]>
  */
 #[AsTwigComponent('component_b', template: 'components/custom1.html.twig')]
 final class ComponentB
 {
+    public string $value;
+
+    #[PreMount]
+    public function preMount(array $data): array
+    {
+        if (isset($data['value'])) {
+            $data['value'] = 'pre-mount '.$data['value'];
+        }
+
+        return $data;
+    }
 }

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

@@ -1 +1,2 @@
 Custom template 1
+b value: {{ this.value }}

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') }}
+{{ component('component_b', { value: 'b value 1' }) }}

src/TwigComponent/tests/Integration/ComponentExtensionTest.php

@@ -38,6 +38,7 @@ public function testCanRenderTheSameComponentMultipleTimes(): void
         $this->assertStringContainsString('propB: prop b value 1', $output);
         $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('service: service a value', $output);
     }