feat: Add support of Twig components extension (#2094)

composer.json

@@ -31,6 +31,7 @@
     "intervention/image": "^3.10",
     "laravel-zero/phar-updater": "^1.4",
     "matthiasmullie/minify": "^1.3",
+    "performing/twig-components": "^0.6",
     "psr/log": "^3.0",
     "psr/simple-cache": "^3.0",
     "scrivo/highlight.php": "^9.18",

config/default.php

@@ -198,6 +198,9 @@
         'extensions' => [ // list of Twig extensions class
             //'<name>' => 'Cecil\Renderer\Extension\<class>',
         ],
+        'components' => [ // components
+            'dir' => 'components', // components directory
+        ],
     ],
     'themes' => [
         'dir' => 'themes', // where themes are stored

docs/3-Templates.md

@@ -1,7 +1,7 @@
 <!--
 description: "Working with layouts and templates."
 date: 2021-05-07
-updated: 2024-01-18
+updated: 2025-01-17
 alias: documentation/layouts
 -->
 # Templates
@@ -1226,6 +1226,29 @@ Supported values are: `short`, `medium`, `long`, and `full`.
 If you want to use the `format_date` filter **with other locales than "en"**, you should [install the intl PHP extension](https://php.net/intl.setup).
 :::
 
+## Components
+
+Cecil provides a components logic to help you build your templates.
+
+```twig
+{# /components/button.twig #}
+<button {{ attributes.merge({class: 'rounded px-4'}) }}>
+    {{ slot }}
+</button>
+
+{# /index.twig #}
+{% x:button with {class: 'text-white'} %}
+    <strong>Click me</strong>
+{% endx %}
+
+{# Rendered #}
+<button class="text-white rounded px-4">
+    <strong>Click me</strong>
+</button>
+```
+
+See official _Twig components extension_ documentation: <https://github.com/giorgiopogliani/twig-components#readme>.
+
 ## Built-in templates
 
 Cecil comes with a set of [built-in templates](https://github.com/Cecilapp/Cecil/tree/master/resources/layouts).

src/Renderer/Twig.php

@@ -17,6 +17,7 @@
 use Cecil\Exception\RuntimeException;
 use Cecil\Renderer\Extension\Core as CoreExtension;
 use Cecil\Util;
+use Performing\TwigComponents\Configuration;
 use Symfony\Bridge\Twig\Extension\TranslationExtension;
 use Symfony\Component\Translation\Formatter\MessageFormatter;
 use Symfony\Component\Translation\IdentityTranslator;
@@ -122,6 +123,11 @@ public function __construct(Builder $builder, $templatesPath)
 
             return false;
         });
+        // components
+        Configuration::make($this->twig)
+            ->setTemplatesPath($this->builder->getConfig()->get('layouts.components.dir') ?? 'components')
+            ->useCustomTags()
+            ->setup();
         // debug
         if ($this->builder->isDebug()) {
             // dump()
@@ -136,7 +142,7 @@ public function __construct(Builder $builder, $templatesPath)
                 try {
                     $this->twig->addExtension(new $class($this->builder));
                     $this->builder->getLogger()->debug(\sprintf('Twig extension "%s" added', $name));
-                } catch (\Exception | \Error $e) {
+                } catch (RuntimeException | \Error $e) {
                     $this->builder->getLogger()->error(\sprintf('Unable to add Twig extension "%s": %s', $name, $e->getMessage()));
                 }
             }

tests/fixtures/website/layouts/components.html.twig

@@ -0,0 +1,15 @@
+{% extends 'page.html.twig' %}
+
+{% block content %}
+    <div>
+      {{ page.content}}
+
+      {% x:button with {'class': 'example-1'} %}
+        <strong>Click me 1</strong>
+      {% endx %}
+
+      <x-button class="example-2">
+        <em>Click me 2</em>
+      </x-button>
+    </div>
+{% endblock %}

tests/fixtures/website/layouts/components/button.twig

@@ -0,0 +1,3 @@
+<button {{ attributes.merge({ class: 'default' }) }}>
+    {{ slot }}
+</button>

tests/fixtures/website/pages/Others/Components.md

@@ -0,0 +1,4 @@
+---
+layout: components
+---
+Components examples: