feature #106 Twig/LiveComponent Attributes (kbond)

This PR was squashed before being merged into the main branch.

Discussion
----------

Twig/LiveComponent Attributes

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | no
| Tickets       | -
| License       | MIT

Based on discussions with `@weaverryan`, the consensus from the core team seems to be to require PHP8+ and use attributes for defining components instead of the interface. The updated [readme](https://github.com/symfony/ux/blob/a80d8df64a41860d2fec407dfecac36ce34809a1/src/TwigComponent/README.md) shows how this would now work.

Assuming this is the direction we want to go, I will update the `LiveComponent` package.

Todo:
- [x] Update `LiveComponent`
- [x] Fix duplicated `LiveProp` [issue](symfony/ux#106 (comment)) on parent classes

Commits
-------

46777c3 Twig/LiveComponent Attributes

Author: weaverryan

README.md

@@ -13,17 +13,13 @@ Every component consists of (1) a class:
 // src/Components/AlertComponent.php
 namespace App\Components;
 
-use Symfony\UX\TwigComponent\ComponentInterface;
+use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;
 
-class AlertComponent implements ComponentInterface
+#[AsTwigComponent('alert')]
+class AlertComponent
 {
     public string $type = 'success';
     public string $message;
-
-    public static function getComponentName(): string
-    {
-        return 'alert';
-    }
 }
 ```
 
@@ -66,28 +62,29 @@ That's it! We're ready to go!
 
 Let's create a reusable "alert" element that we can use to show
 success or error messages across our site. Step 1 is always to create
-a component that implements `ComponentInterface`. Let's start as simple
-as possible:
+a component that has an `AsTwigComponent` class attribute. Let's start as
+simple as possible:
 
 ```php
 // src/Components/AlertComponent.php
 namespace App\Components;
 
-use Symfony\UX\TwigComponent\ComponentInterface;
+use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;
 
-class AlertComponent implements ComponentInterface
+#[AsTwigComponent('alert')]
+class AlertComponent
 {
-    public static function getComponentName(): string
-    {
-        return 'alert';
-    }
 }
 ```
 
-Step 2 is to create a template for this component. Templates live
-in `templates/components/{Component Name}.html.twig`, where
-`{Component Name}` is whatever you return from the `getComponentName()`
-method:
+**Note:** If this class is auto-configured, _and_ you're using Symfony 5.3+,
+then you're all set. Otherwise, register the service and tag it with
+`twig.component`.
+
+Step 2 is to create a template for this component. By default,
+templates live in `templates/components/{Component Name}.html.twig`,
+where `{Component Name}` is whatever you passed as the first argument
+to the `AsTwigComponent` class attribute:
 
 ```twig
 {# templates/components/alert.html.twig #}
@@ -118,7 +115,8 @@ that, create a public property for each:
 // src/Components/AlertComponent.php
 // ...
 
-class AlertComponent implements ComponentInterface
+#[AsTwigComponent('alert')]
+class AlertComponent
 {
 +    public string $message;
 
@@ -155,6 +153,23 @@ property of the object. Then, the component is rendered! If a
 property has a setter method (e.g. `setMessage()`), that will
 be called instead of setting the property directly.
 
+### Customize the Twig Template
+
+You can customize the template used to render the template by
+passing it as the second argument to the `AsTwigComponent` attribute:
+
+```diff
+// src/Components/AlertComponent.php
+// ...
+
+-#[AsTwigComponent('alert')]
++#[AsTwigComponent('alert', 'my/custom/template.html.twig')]
+class AlertComponent
+{
+    // ...
+}
+```
+
 ### The mount() Method
 
 If, for some reason, you don't want an option to the `component()`
@@ -165,7 +180,8 @@ a `mount()` method in your component:
 // src/Components/AlertComponent.php
 // ...
 
-class AlertComponent implements ComponentInterface
+#[AsTwigComponent('alert')]
+class AlertComponent
 {
     public string $message;
     public string $type = 'success';
@@ -211,9 +227,10 @@ Doctrine entity and `ProductRepository`:
 namespace App\Components;
 
 use App\Repository\ProductRepository;
-use Symfony\UX\TwigComponent\ComponentInterface;
+use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;
 
-class FeaturedProductsComponent implements ComponentInterface
+#[AsTwigComponent('featured_products')]
+class FeaturedProductsComponent
 {
     private ProductRepository $productRepository;
 
@@ -227,11 +244,6 @@ class FeaturedProductsComponent implements ComponentInterface
         // an example method that returns an array of Products
         return $this->productRepository->findFeatured();
     }
-
-    public static function getComponentName() : string
-    {
-        return 'featured_products';
-    }
 }
 ```
 
@@ -291,7 +303,8 @@ method), you can store its result on a private property:
 namespace App\Components;
 // ...
 
-class FeaturedProductsComponent implements ComponentInterface
+#[AsTwigComponent('featured_products')]
+class FeaturedProductsComponent
 {
     private ProductRepository $productRepository;
 

composer.json

@@ -26,7 +26,7 @@
         }
     },
     "require": {
-        "php": ">=7.2.5",
+        "php": ">=8.0",
         "twig/twig": "^2.0|^3.0",
         "symfony/property-access": "^4.4|^5.0",
         "symfony/dependency-injection": "^4.4|^5.0"

src/Attribute/AsTwigComponent.php

@@ -0,0 +1,56 @@
+<?php
+
+/*
+ * 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.
+ */
+
+namespace Symfony\UX\TwigComponent\Attribute;
+
+/**
+ * @author Kevin Bond <[email protected]>
+ *
+ * @experimental
+ */
+#[\Attribute(\Attribute::TARGET_CLASS)]
+class AsTwigComponent
+{
+    private string $name;
+    private ?string $template;
+
+    public function __construct(string $name, ?string $template = null)
+    {
+        $this->name = $name;
+        $this->template = $template;
+    }
+
+    final public function getName(): string
+    {
+        return $this->name;
+    }
+
+    final public function getTemplate(): string
+    {
+        return $this->template ?? "components/{$this->name}.html.twig";
+    }
+
+    /**
+     * @internal
+     *
+     * @return static
+     */
+    final public static function forClass(string $class): self
+    {
+        $class = new \ReflectionClass($class);
+
+        if (!$attribute = $class->getAttributes(static::class, \ReflectionAttribute::IS_INSTANCEOF)[0] ?? null) {
+            throw new \InvalidArgumentException(sprintf('"%s" is not a Twig Component, did you forget to add the "%s" attribute?', $class, static::class));
+        }
+
+        return $attribute->newInstance();
+    }
+}

src/ComponentFactory.php

@@ -21,24 +21,19 @@
  */
 final class ComponentFactory
 {
-    private $components;
-    private $propertyAccessor;
-    private $serviceIdMap;
+    private ServiceLocator $components;
+    private PropertyAccessorInterface $propertyAccessor;
 
-    /**
-     * @param ServiceLocator|ComponentInterface[] $components
-     */
-    public function __construct(ServiceLocator $components, PropertyAccessorInterface $propertyAccessor, array $serviceIdMap)
+    public function __construct(ServiceLocator $components, PropertyAccessorInterface $propertyAccessor)
     {
         $this->components = $components;
         $this->propertyAccessor = $propertyAccessor;
-        $this->serviceIdMap = $serviceIdMap;
     }
 
     /**
      * Creates the component and "mounts" it with the passed data.
      */
-    public function create(string $name, array $data = []): ComponentInterface
+    public function create(string $name, array $data = []): object
     {
         $component = $this->getComponent($name);
 
@@ -59,21 +54,12 @@ public function create(string $name, array $data = []): ComponentInterface
     /**
      * Returns the "unmounted" component.
      */
-    public function get(string $name): ComponentInterface
+    public function get(string $name): object
     {
         return $this->getComponent($name);
     }
 
-    public function serviceIdFor(string $name): string
-    {
-        if (!isset($this->serviceIdMap[$name])) {
-            throw new \InvalidArgumentException('Component not found.');
-        }
-
-        return $this->serviceIdMap[$name];
-    }
-
-    private function mount(ComponentInterface $component, array &$data): void
+    private function mount(object $component, array &$data): void
     {
         try {
             $method = (new \ReflectionClass($component))->getMethod('mount');
@@ -102,10 +88,10 @@ private function mount(ComponentInterface $component, array &$data): void
         $component->mount(...$parameters);
     }
 
-    private function getComponent(string $name): ComponentInterface
+    private function getComponent(string $name): object
     {
         if (!$this->components->has($name)) {
-            throw new \InvalidArgumentException(sprintf('Unknown component "%s". The registered components are: %s', $name, implode(', ', array_keys($this->serviceIdMap))));
+            throw new \InvalidArgumentException(sprintf('Unknown component "%s". The registered components are: %s', $name, implode(', ', array_keys($this->components->getProvidedServices()))));
         }
 
         return $this->components->get($name);

src/ComponentInterface.php

@@ -11,6 +11,7 @@
 
 namespace Symfony\UX\TwigComponent;
 
+use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;
 use Twig\Environment;
 
 /**
@@ -20,19 +21,18 @@
  */
 final class ComponentRenderer
 {
-    private $twig;
+    private Environment $twig;
 
     public function __construct(Environment $twig)
     {
         $this->twig = $twig;
     }
 
-    public function render(ComponentInterface $component): string
+    public function render(object $component): string
     {
-        // TODO: Template attribute/annotation/interface to customize
         // TODO: Self-Rendering components?
-        $templateName = sprintf('components/%s.html.twig', $component::getComponentName());
+        $attribute = AsTwigComponent::forClass($component::class);
 
-        return $this->twig->render($templateName, ['this' => $component]);
+        return $this->twig->render($attribute->getTemplate(), ['this' => $component]);
     }
 }

src/ComponentRenderer.php

@@ -11,10 +11,12 @@
 
 namespace Symfony\UX\TwigComponent\DependencyInjection\Compiler;
 
+use Symfony\Component\DependencyInjection\Argument\ServiceLocatorArgument;
 use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 use Symfony\Component\DependencyInjection\Exception\LogicException;
-use Symfony\UX\TwigComponent\ComponentFactory;
+use Symfony\Component\DependencyInjection\Reference;
+use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;
 
 /**
  * @author Kevin Bond <[email protected]>
@@ -25,25 +27,25 @@ final class TwigComponentPass implements CompilerPassInterface
 {
     public function process(ContainerBuilder $container): void
     {
-        $serviceIdMap = [];
+        $componentMap = [];
 
-        foreach (array_keys($container->findTaggedServiceIds('twig.component')) as $serviceId) {
-            $definition = $container->getDefinition($serviceId);
+        foreach (array_keys($container->findTaggedServiceIds('twig.component')) as $id) {
+            $componentDefinition = $container->findDefinition($id);
 
-            // make all component services non-shared
-            $definition->setShared(false);
-
-            $name = $definition->getClass()::getComponentName();
-
-            // ensure component not already defined
-            if (\array_key_exists($name, $serviceIdMap)) {
-                throw new LogicException(sprintf('Component "%s" is already registered as "%s", components cannot be registered more than once.', $definition->getClass(), $serviceIdMap[$name]));
+            try {
+                $attribute = AsTwigComponent::forClass($componentDefinition->getClass());
+            } catch (\InvalidArgumentException $e) {
+                throw new LogicException(sprintf('Service "%s" is tagged as a "twig.component" but does not have a "%s" class attribute.', $id, AsTwigComponent::class), 0, $e);
             }
 
-            // add to service id map for ComponentFactory
-            $serviceIdMap[$name] = $serviceId;
+            $componentMap[$attribute->getName()] = new Reference($id);
+
+            // component services must not be shared
+            $componentDefinition->setShared(false);
         }
 
-        $container->getDefinition(ComponentFactory::class)->setArgument(2, $serviceIdMap);
+        $container->findDefinition('ux.twig_component.component_factory')
+            ->setArgument(0, new ServiceLocatorArgument($componentMap))
+        ;
     }
 }