[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 non-public 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 as variables directly
+ * in a component template (`someProp` vs `this.someProp`). These
+ * properties must be "accessible" (have a getter).
+ *
+ * @author Kevin Bond <[email protected]>
+ *
+ * @experimental
+ */
+#[\Attribute(\Attribute::TARGET_PROPERTY)]
+final class ExposeInTemplate
+{
+    /**
+     * @param string|null $name   The variable name to expose. Leave as null
+     *                            to default to property name.
+     * @param string|null $getter The getter method to use. Leave as null
+     *                            to default to PropertyAccessor logic.
+     */
+    public function __construct(public ?string $name = null, public ?string $getter = 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;
@@ -28,7 +30,8 @@ final class ComponentRenderer
     public function __construct(
         private Environment $twig,
         private EventDispatcherInterface $dispatcher,
-        private ComponentFactory $factory
+        private ComponentFactory $factory,
+        private PropertyAccessorInterface $propertyAccessor
     ) {
     }
 
@@ -40,10 +43,42 @@ public function render(MountedComponent $mounted): string
             $this->safeClassesRegistered = true;
         }
 
-        $event = new PreRenderEvent($mounted, $this->factory->metadataFor($mounted->getName()));
+        $component = $mounted->getComponent();
+        $variables = array_merge(
+            // add the component as "this"
+            ['this' => $component],
+
+            // add attributes
+            ['attributes' => $mounted->getAttributes()],
+
+            // expose all public properties
+            get_object_vars($component),
+
+            // expose non-public properties marked with ExposeInTemplate attribute
+            iterator_to_array($this->exposedVariables($component)),
+        );
+        $event = new PreRenderEvent($mounted, $this->factory->metadataFor($mounted->getName()), $variables);
 
         $this->dispatcher->dispatch($event);
 
         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;
+            }
+
+            $attribute = $attribute->newInstance();
+
+            /** @var ExposeInTemplate $attribute */
+            $value = $attribute->getter ? $component->{rtrim($attribute->getter, '()')}() : $this->propertyAccessor->getValue($component, $property->name);
+
+            yield $attribute->name ?? $property->name => $value;
+        }
+    }
 }

src/TwigComponent/src/DependencyInjection/TwigComponentExtension.php

@@ -57,6 +57,7 @@ class_exists(AbstractArgument::class) ? new AbstractArgument(sprintf('Added in %
                 new Reference('twig'),
                 new Reference('event_dispatcher'),
                 new Reference('ux.twig_component.component_factory'),
+                new Reference('property_accessor'),
             ])
         ;
 

src/TwigComponent/src/EventListener/PreRenderEvent.php

@@ -23,15 +23,16 @@
 final class PreRenderEvent extends Event
 {
     private string $template;
-    private array $variables;
 
     /**
      * @internal
      */
-    public function __construct(private MountedComponent $mounted, private ComponentMetadata $metadata)
-    {
+    public function __construct(
+        private MountedComponent $mounted,
+        private ComponentMetadata $metadata,
+        private array $variables
+    ) {
         $this->template = $this->metadata->getTemplate();
-        $this->variables = $this->mounted->getVariables();
     }
 
     /**

src/TwigComponent/src/MountedComponent.php

@@ -41,12 +41,4 @@ public function getAttributes(): ComponentAttributes
     {
         return $this->attributes;
     }
-
-    public function getVariables(): array
-    {
-        return array_merge(
-            ['this' => $this->component, 'attributes' => $this->attributes],
-            get_object_vars($this->component)
-        );
-    }
 }

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

@@ -219,6 +219,60 @@ 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 directly in a component template (``someProp``
+vs ``this.someProp``). These properties 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(name: 'ico', getter: 'fetchIcon')]
+        private string $icon = 'ico-warning'; // available as `{{ ico }}` in the template using `fetchIcon()` as the getter
+
+        /**
+         * Required to access $this->message
+         */
+        public function getMessage(): string
+        {
+            return $this->message;
+        }
+
+        /**
+         * Required to access $this->type
+         */
+        public function getType(): string
+        {
+            return $this->type;
+        }
+
+        /**
+         * Required to access $this->icon
+         */
+        public function fetchIcon(): string
+        {
+            return $this->icon;
+        }
+
+        // ...
+    }
+
 PreMount Hook
 ~~~~~~~~~~~~~
 

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

@@ -0,0 +1,37 @@
+<?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('customProp2')]
+    private string $prop2 = 'prop2 value';
+
+    #[ExposeInTemplate('customProp3', getter: 'customGetter()')]
+    private string $prop3 = 'prop3 value';
+
+    public function getProp1(): string
+    {
+        return $this->prop1;
+    }
+
+    public function getProp2(): string
+    {
+        return $this->prop2;
+    }
+
+    public function customGetter(): string
+    {
+        return $this->prop3;
+    }
+}

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,3 @@
+Prop1: {{ prop1 }}
+Prop2: {{ customProp2 }}
+Prop3: {{ customProp3 }}