[Twig] add computed method system

Author: kbond

src/TwigComponent/CHANGELOG.md

@@ -13,6 +13,8 @@
 
 -   Add `PreRenderEvent` to intercept/manipulate twig template/variables before rendering.
 
+-   Add _Computed Method_ system.
+
 ## 2.0.0
 
 -   Support for `stimulus` version 2 was removed and support for `@hotwired/stimulus`

src/TwigComponent/src/ComponentRenderer.php

@@ -40,7 +40,11 @@ public function render(object $component, ComponentMetadata $metadata): string
         $event = new PreRenderEvent(
             $component,
             $metadata,
-            array_merge(['this' => $component], get_object_vars($component))
+            array_merge(
+                ['this' => $component],
+                get_object_vars($component),
+                ['computed' => new ComputedMethodProxy($component)],
+            )
         );
 
         $this->dispatcher->dispatch($event);

src/TwigComponent/src/ComputedMethodProxy.php

@@ -0,0 +1,58 @@
+<?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;
+
+/**
+ * @author Kevin Bond <[email protected]>
+ *
+ * @experimental
+ */
+final class ComputedMethodProxy
+{
+    private array $cache = [];
+
+    public function __construct(private object $component)
+    {
+    }
+
+    public function __call(string $name, array $arguments): mixed
+    {
+        if ($arguments) {
+            throw new \InvalidArgumentException('Passing arguments to computed methods is not supported.');
+        }
+
+        $method = $this->normalizeMethod($name);
+
+        if (isset($this->cache[$method])) {
+            return $this->cache[$method];
+        }
+
+        if ((new \ReflectionMethod($this->component, $method))->getNumberOfRequiredParameters()) {
+            throw new \LogicException('Cannot use computed methods for methods with required parameters.');
+        }
+
+        return $this->cache[$method] = $this->component->$method();
+    }
+
+    private function normalizeMethod(string $name): string
+    {
+        if (method_exists($this->component, $name)) {
+            return $name;
+        }
+
+        if (method_exists($this->component, $getter = sprintf('get%s', ucfirst($name)))) {
+            return $getter;
+        }
+
+        throw new \InvalidArgumentException(sprintf('Component "%s" does not have a "%s" or "%s" method.', $this->component::class, $name, $getter));
+    }
+}

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

@@ -360,8 +360,12 @@ need to populate, you can render it with:
     means that you can safely render the same component multiple times with
     different data because each component will be an independent instance.
 
-Computed Properties
-~~~~~~~~~~~~~~~~~~~
+Computed Methods
+~~~~~~~~~~~~~~~~
+
+.. versionadded:: 2.1
+
+    Computed Methods were added in TwigComponents 2.1.
 
 In the previous example, instead of querying for the featured products
 immediately (e.g. in ``__construct()``), we created a ``getProducts()``
@@ -378,35 +382,32 @@ But there's no magic with the ``getProducts()`` method: if you call
 ``this.products`` multiple times in your template, the query would be
 executed multiple times.
 
-To make your ``getProducts()`` method act like a true computed property
-(where its value is only evaluated the first time you call the method),
-you can store its result on a private property:
+To make your ``getProducts()`` method act like a true computed property,
+call ``computed.products`` in your template. ``computed`` is a proxy
+that wraps your component and caches the return of methods. If they
+are called additional times, the cached value is used.
 
-.. code-block:: diff
+.. code-block:: twig
 
-      // src/Components/FeaturedProductsComponent.php
-      namespace App\Components;
-      // ...
+    {# templates/components/featured_products.html.twig #}
 
-      #[AsTwigComponent('featured_products')]
-      class FeaturedProductsComponent
-      {
-          private ProductRepository $productRepository;
+    <div>
+        <h3>Featured Products</h3>
 
-    +     private ?array $products = null;
+        {% for product in computed.products %}
+            ...
+        {% endfor %}
 
-          // ...
+        ...
+        {% for product in computed.products %} {# use cache, does not result in a second query #}
+            ...
+        {% endfor %}
+    </div>
 
-          public function getProducts(): array
-          {
-    +         if ($this->products === null) {
-    +             $this->products = $this->productRepository->findFeatured();
-    +         }
+.. note::
 
-    -         return $this->productRepository->findFeatured();
-    +         return $this->products;
-          }
-      }
+    Computed methods only work for component methods with no required
+    arguments.
 
 Component Attributes
 --------------------

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

@@ -24,6 +24,7 @@ final class ComponentA
 
     private $propB;
     private $service;
+    private $count = 0;
 
     public function __construct(ServiceA $service)
     {
@@ -44,4 +45,9 @@ public function getPropB()
     {
         return $this->propB;
     }
+
+    public function getCount()
+    {
+        return ++$this->count;
+    }
 }

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

@@ -1,3 +1,8 @@
 propA: {{ propA }}
 propB: {{ this.propB }}
 service: {{ this.service.value }}
+countDirect1: {{ this.getCount }}
+countDirect2: {{ this.count }}
+countComputed1: {{ computed.getCount }}
+countComputed2: {{ computed.count }}
+countComputed3: {{ computed.count }}

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 testCanUseComputedMethods(): void
+    {
+        $output = self::getContainer()->get(Environment::class)->render('template_a.html.twig');
+
+        $this->assertStringContainsString('countDirect1: 1', $output);
+        $this->assertStringContainsString('countDirect2: 2', $output);
+        $this->assertStringContainsString('countComputed1: 3', $output);
+        $this->assertStringContainsString('countComputed2: 3', $output);
+        $this->assertStringContainsString('countComputed3: 3', $output);
+    }
 }

src/TwigComponent/tests/Unit/ComputedMethodProxyTest.php

@@ -0,0 +1,60 @@
+<?php
+
+namespace Symfony\UX\TwigComponent\Tests\Unit;
+
+use PHPUnit\Framework\TestCase;
+use Symfony\UX\TwigComponent\ComputedMethodProxy;
+
+/**
+ * @author Kevin Bond <[email protected]>
+ */
+final class ComputedMethodProxyTest extends TestCase
+{
+    public function testProxyCachesMethodReturns(): void
+    {
+        $proxy = new ComputedMethodProxy(new class() {
+            private int $count = 0;
+
+            public function getCount(): int
+            {
+                return ++$this->count;
+            }
+        });
+
+        $this->assertSame(1, $proxy->getCount());
+        $this->assertSame(1, $proxy->getCount());
+        $this->assertSame(1, $proxy->count());
+    }
+
+    public function testCannotProxyMethodsThatDoNotExist(): void
+    {
+        $proxy = new ComputedMethodProxy(new class() {});
+
+        $this->expectException(\InvalidArgumentException::class);
+
+        $proxy->getSomething();
+    }
+
+    public function testCannotPassArgumentsToProxiedMethods(): void
+    {
+        $proxy = new ComputedMethodProxy(new class() {});
+
+        $this->expectException(\InvalidArgumentException::class);
+
+        $proxy->getSomething('foo');
+    }
+
+    public function testCannotProxyMethodsWithRequiredArguments(): void
+    {
+        $proxy = new ComputedMethodProxy(new class() {
+            public function getValue(int $value): int
+            {
+                return $value;
+            }
+        });
+
+        $this->expectException(\LogicException::class);
+
+        $proxy->getValue();
+    }
+}