[Twig] ComponentAttributes::append()/prepend()

Author: kbond

src/TwigComponent/doc/index.rst

@@ -952,14 +952,21 @@ Render
 
     The ability to *render* attributes was added in TwigComponents 2.15.
 
+.. versionadded:: 2.15
+
+    The ability to *render* attributes with a default, *prepend*, and *append* were
+    added in TwigComponents 2.15.
+
 You can take full control over the attributes that are rendered by using the
-``render()`` method.
+``render()``, ``prepend()``, and ``append()`` methods.
 
 .. code-block:: html+twig
 
     {# templates/components/MyComponent.html.twig #}
     <div
-      style="{{ attributes.render('style') }} display:block;"
+      class="{{ attributes.render('class', 'default') }}" {# second parameter is the default value #}
+      style="{{ attributes.append('style', 'display:block;') }}" {# second parameter value to append #}
+      data-controller="{{ attributes.append('data-controller', 'hello-controller') }}" {# second parameter value to prepend #}
       {{ attributes }} {# be sure to always render the remaining attributes! #}
     >
       My Component!
@@ -969,15 +976,15 @@ You can take full control over the attributes that are rendered by using the
     {{ component('MyComponent', { style: 'color:red;' }) }}
 
     {# renders as: #}
-    <div style="color:red; display:block;">
+    <div class="default" style="color:red; display:block;" data-controller="hello-controller">
       My Component!
     </div>
 
 .. caution::
 
-    There are a few important things to know about using ``render()``:
+    There are a few important things to know about using ``render()``/``prepend()``/``append()``:
 
-    1. You need to be sure to call your ``render()`` methods before calling ``{{ attributes }}`` or some
+    1. You need to be sure to call these methods before calling ``{{ attributes }}`` or some
        attributes could be rendered twice. For instance:
 
             .. code-block:: html+twig
@@ -998,7 +1005,7 @@ You can take full control over the attributes that are rendered by using the
                     My Component!
                 </div>
 
-    2. If you add an attribute without calling ``render()``, it will be rendered twice. For instance:
+    2. If you add an attribute without calling these methods, it will be rendered twice. For instance:
 
          .. code-block:: html+twig
 

src/TwigComponent/src/ComponentAttributes.php

@@ -65,10 +65,10 @@ public function __clone(): void
         $this->rendered = [];
     }
 
-    public function render(string $attribute): ?string
+    public function render(string $attribute, ?string $default = null): ?string
     {
         if (null === $value = $this->attributes[$attribute] ?? null) {
-            return null;
+            return $default;
         }
 
         if (!\is_string($value)) {
@@ -80,6 +80,16 @@ public function render(string $attribute): ?string
         return $value;
     }
 
+    public function prepend(string $attribute, string $value, string $separator = ' '): string
+    {
+        return trim(sprintf('%s%s%s', $value, $separator, $this->render($attribute)));
+    }
+
+    public function append(string $attribute, string $value, string $separator = ' '): string
+    {
+        return trim(sprintf('%s%s%s', $this->render($attribute), $separator, $value));
+    }
+
     /**
      * @return array<string, string|bool>
      */

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

@@ -1,7 +1,10 @@
 <div
-    foo="{{ attributes.render('foo') }}"
-    bar="{{ attributes.render('bar')|default('default') }}"
-    baz="default {{ attributes.render('baz') }}"
-    qux="{{ attributes.render('qux') }} default"
+    attr1="{{ attributes.render('attr1') }}"
+    attr2="{{ attributes.render('attr2')|default('default') }}"
+    attr3="default {{ attributes.render('attr3') }}"
+    attr4="{{ attributes.render('attr4') }} default"
+    attr5="{{ attributes.render('attr5', 'default') }}"
+    attr6="{{ attributes.prepend('attr6', 'default') }}"
+    attr7="{{ attributes.append('attr7', 'default') }}"
     {{ attributes }}
 />

src/TwigComponent/tests/Integration/ComponentExtensionTest.php

@@ -228,10 +228,13 @@ public static function renderingAttributesManuallyProvider(): iterable
             ['class' => 'block'],
             <<<HTML
             <div
-                foo=""
-                bar="default"
-                baz="default "
-                qux=" default"
+                attr1=""
+                attr2="default"
+                attr3="default "
+                attr4=" default"
+                attr5="default"
+                attr6="default"
+                attr7="default"
                  class="block"
             />
             HTML,
@@ -240,17 +243,23 @@ class="block"
         yield [
             [
                 'class' => 'block',
-                'foo' => 'value',
-                'bar' => 'value',
-                'baz' => 'value',
-                'qux' => 'value',
+                'attr1' => 'value1',
+                'attr2' => 'value2',
+                'attr3' => 'value3',
+                'attr4' => 'value4',
+                'attr5' => 'value5',
+                'attr6' => 'value6',
+                'attr7' => 'value7',
             ],
             <<<HTML
             <div
-                foo="value"
-                bar="value"
-                baz="default value"
-                qux="value default"
+                attr1="value1"
+                attr2="value2"
+                attr3="default value3"
+                attr4="value4 default"
+                attr5="value5"
+                attr6="default value6"
+                attr7="value7 default"
                  class="block"
             />
             HTML,

src/TwigComponent/tests/Unit/ComponentAttributesTest.php

@@ -200,20 +200,21 @@ public function testIsTraversableAndCountable(): void
         $this->assertCount(1, $attributes);
     }
 
-    public function testRenderSingleAttribute(): void
+    public function testRenderAttributes(): void
     {
-        $attributes = new ComponentAttributes(['attr1' => 'value1', 'attr2' => 'value2']);
-
-        $this->assertSame('value1', $attributes->render('attr1'));
-        $this->assertNull($attributes->render('attr3'));
-    }
-
-    public function testRenderingSingleAttributeExcludesFromString(): void
-    {
-        $attributes = new ComponentAttributes(['attr1' => 'value1', 'attr2' => 'value2']);
+        $attributes = new ComponentAttributes([
+            'attr1' => 'value1',
+            'attr2' => 'value2',
+            'attr3' => 'value3',
+            'attr4' => 'value4',
+        ]);
 
         $this->assertSame('value1', $attributes->render('attr1'));
-        $this->assertSame(' attr2="value2"', (string) $attributes);
+        $this->assertSame('default value2', $attributes->prepend('attr2', 'default'));
+        $this->assertSame('value3 default', $attributes->append('attr3', 'default'));
+        $this->assertNull($attributes->render('attr5'));
+        $this->assertSame('default', $attributes->render('attr5', 'default'));
+        $this->assertSame(' attr4="value4"', (string) $attributes);
     }
 
     public function testCannotRenderNonStringAttribute(): void