[Twig] add ExposeInTemplate attribute

Author: kbond

src/TwigComponent/CHANGELOG.md

@@ -13,6 +13,9 @@
 
 -   Add `PreRenderEvent` to intercept/manipulate twig template/variables before rendering.
 
+-   Add `ExposeInTemplate` attribute to make methods/properties available in component templates
+    directly.
+
 ## 2.0.0
 
 -   Support for `stimulus` version 2 was removed and support for `@hotwired/stimulus`

src/TwigComponent/src/Attribute/ExposeInTemplate.php

@@ -0,0 +1,35 @@
+<?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;
+
+/**
+ * Use to expose private/protected properties and public methods
+ * as variables directly in a component template (`someProp` vs
+ * `this.someProp`). For properties, they must be "accessible"
+ * (have a getter).
+ *
+ * @author Kevin Bond <[email protected]>
+ *
+ * @experimental
+ */
+#[\Attribute(\Attribute::TARGET_PROPERTY | \Attribute::TARGET_METHOD)]
+final class ExposeInTemplate
+{
+    /**
+     * @param string|null $name The variable name to expose. Leave as null
+     *                          to default to property/method name. Getter
+     *                          methods will have their "get" prefix removed.
+     */
+    public function __construct(public ?string $name = null)
+    {
+    }
+}

src/TwigComponent/src/ComponentRenderer.php

@@ -11,7 +11,9 @@
 
 namespace Symfony\UX\TwigComponent;
 
+use Symfony\Component\PropertyAccess\PropertyAccessorInterface;
 use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;
+use Symfony\UX\TwigComponent\Attribute\ExposeInTemplate;
 use Symfony\UX\TwigComponent\EventListener\PreRenderEvent;
 use Twig\Environment;
 use Twig\Extension\EscaperExtension;
@@ -25,7 +27,7 @@ final class ComponentRenderer
 {
     private bool $safeClassesRegistered = false;
 
-    public function __construct(private Environment $twig, private EventDispatcherInterface $dispatcher)
+    public function __construct(private Environment $twig, private EventDispatcherInterface $dispatcher, private PropertyAccessorInterface $propertyAccessor)
     {
     }
 
@@ -37,14 +39,44 @@ public function render(object $component, ComponentMetadata $metadata): string
             $this->safeClassesRegistered = true;
         }
 
-        $event = new PreRenderEvent(
-            $component,
-            $metadata,
-            array_merge(['this' => $component], get_object_vars($component))
+        $variables = array_merge(
+            // add the component as "this"
+            ['this' => $component],
+
+            // expose all public properties
+            get_object_vars($component),
+
+            // expose properties/methods marked with ExposeInTemplate attribute
+            iterator_to_array($this->exposedVariables($component)),
         );
 
-        $this->dispatcher->dispatch($event);
+        $this->dispatcher->dispatch($event = new PreRenderEvent($component, $metadata, $variables));
 
         return $this->twig->render($event->getTemplate(), $event->getVariables());
     }
+
+    private function exposedVariables(object $component): \Iterator
+    {
+        $class = new \ReflectionClass($component);
+
+        foreach ($class->getProperties() as $property) {
+            if (!$attribute = $property->getAttributes(ExposeInTemplate::class)[0] ?? null) {
+                continue;
+            }
+
+            yield $attribute->newInstance()->name ?? $property->name => $this->propertyAccessor->getValue($component, $property->name);
+        }
+
+        foreach ($class->getMethods(\ReflectionMethod::IS_PUBLIC) as $method) {
+            if (!$attribute = $method->getAttributes(ExposeInTemplate::class)[0] ?? null) {
+                continue;
+            }
+
+            if (!($name = $attribute->newInstance()->name) && str_starts_with($name = $method->name, 'get')) {
+                $name = lcfirst(substr($name, 3));
+            }
+
+            yield $name => $component->{$method->name}();
+        }
+    }
 }

src/TwigComponent/src/DependencyInjection/TwigComponentExtension.php

@@ -56,6 +56,7 @@ class_exists(AbstractArgument::class) ? new AbstractArgument(sprintf('Added in %
             ->setArguments([
                 new Reference('twig'),
                 new Reference('event_dispatcher'),
+                new Reference('property_accessor'),
             ])
         ;
 

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

@@ -219,6 +219,62 @@ 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.
 
+ExposeInTemplate Attribute
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 2.1
+
+    The ``ExposeInTemplate`` attribute was added in TwigComponents 2.1.
+
+All public component properties are available directly in your component
+template. You can use the ``ExposeInTemplate`` attribute to expose
+private/protected properties and public methods as variables directly in a
+component template (``someProp`` vs ``this.someProp``). For properties, they
+must be *accessible* (have a getter).
+
+    // ...
+    use Symfony\UX\TwigComponent\Attribute\ExposeInTemplate;
+
+    #[AsTwigComponent('alert')]
+    class AlertComponent
+    {
+        #[ExposeInTemplate]
+        private string $message; // available as `{{ message }}` in the template
+
+        #[ExposeInTemplate('alert_type')]
+        private string $type = 'success'; // available as `{{ alert_type }}` in the template
+
+        #[ExposeInTemplate]
+        public function getIcon(): string
+        {
+            // return value will be available as `{{ icon }}` in the template (note the get prefix is trimmed)
+        }
+
+        /**
+         * Required to access $this->message
+         */
+        public function getMessage(): string
+        {
+            return $this->message;
+        }
+
+        /**
+         * Required to access $this->type
+         */
+        public function getType(): string
+        {
+            return $this->type;
+        }
+
+        // ...
+    }
+
+.. note::
+
+    When ``#[ExposeInTemplate]`` is used above a method, that method will be called one
+    time before the template is rendered. It effectively makes the method a *non-lazy
+    computed property*.
+
 PreMount Hook
 ~~~~~~~~~~~~~
 

src/TwigComponent/tests/Fixtures/Component/WithExposedVariables.php

@@ -0,0 +1,47 @@
+<?php
+
+namespace Symfony\UX\TwigComponent\Tests\Fixtures\Component;
+
+use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;
+use Symfony\UX\TwigComponent\Attribute\ExposeInTemplate;
+
+/**
+ * @author Kevin Bond <[email protected]>
+ */
+#[AsTwigComponent('with_exposed_variables')]
+final class WithExposedVariables
+{
+    #[ExposeInTemplate]
+    private string $prop1 = 'prop1 value';
+
+    #[ExposeInTemplate('customProp')]
+    private string $prop2 = 'prop2 value';
+
+    public function getProp1(): string
+    {
+        return $this->prop1;
+    }
+
+    public function getProp2(): string
+    {
+        return $this->prop2;
+    }
+
+    #[ExposeInTemplate]
+    public function method1(): string
+    {
+        return 'method1 value';
+    }
+
+    #[ExposeInTemplate]
+    public function getMethod2(): string
+    {
+        return 'method2 value';
+    }
+
+    #[ExposeInTemplate('customMethod')]
+    public function getMethod3(): string
+    {
+        return 'method3 value';
+    }
+}

src/TwigComponent/tests/Fixtures/Kernel.php

@@ -17,6 +17,7 @@
 use Symfony\Component\Config\Loader\LoaderInterface;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 use Symfony\Component\HttpKernel\Kernel as BaseKernel;
+use Symfony\UX\TwigComponent\Tests\Fixtures\Component\WithExposedVariables;
 use Symfony\UX\TwigComponent\Tests\Fixtures\Component\ComponentA;
 use Symfony\UX\TwigComponent\Tests\Fixtures\Component\ComponentB;
 use Symfony\UX\TwigComponent\Tests\Fixtures\Component\ComponentC;
@@ -59,6 +60,7 @@ protected function configureContainer(ContainerBuilder $c, LoaderInterface $load
             'key' => 'component_d',
             'template' => 'components/custom2.html.twig',
         ]);
+        $c->register(WithExposedVariables::class)->setAutoconfigured(true)->setAutowired(true);
 
         if ('missing_key' === $this->environment) {
             $c->register('missing_key', ComponentB::class)->setAutowired(true)->addTag('twig.component');

src/TwigComponent/tests/Fixtures/templates/components/with_exposed_variables.html.twig

@@ -0,0 +1,5 @@
+Prop1: {{ prop1 }}
+Prop2: {{ customProp }}
+Method1: {{ method1 }}
+Method2: {{ method2 }}
+Method3: {{ customMethod }}

src/TwigComponent/tests/Fixtures/templates/exposed_variables.html.twig

@@ -0,0 +1 @@
+{{ component('with_exposed_variables') }}

src/TwigComponent/tests/Integration/ComponentExtensionTest.php

@@ -64,4 +64,15 @@ public function testCanRenderComponentWithAttributes(): void
         $this->assertStringContainsString('Component Content (prop value 2)', $output);
         $this->assertStringContainsString('<button class="foo baz" type="submit" style="color:red;">', $output);
     }
+
+    public function testRenderComponentWithExposedVariables(): void
+    {
+        $output = self::getContainer()->get(Environment::class)->render('exposed_variables.html.twig');
+
+        $this->assertStringContainsString('Prop1: prop1 value', $output);
+        $this->assertStringContainsString('Prop2: prop2 value', $output);
+        $this->assertStringContainsString('Method1: method1 value', $output);
+        $this->assertStringContainsString('Method2: method2 value', $output);
+        $this->assertStringContainsString('Method3: method3 value', $output);
+    }
 }