Symfony UX TwigComponent: Wiederverwendbare Blöcke bauen

1. Warum TwigComponent statt Twig-Include

Das klassische Twig-include teilt Templates in Partials auf, die an beliebigen Stellen eingebunden werden. Das funktioniert gut für einfache Fälle, stößt aber an Grenzen, sobald eine Komponente Logik benötigt. Ein Button, der automatisch seine Route aufruft, eine Karte, die Daten aus dem aktuellen Kontext liest, oder ein Alert, der verschiedene Varianten (success, error, warning) kennt — all das erfordert mit include entweder viele with-Parameter oder Logik im aufrufenden Template. Symfony UX TwigComponent löst das mit einer sauberen Komponentenarchitektur: Props definieren die Eingabe, eine optionale PHP-Klasse enthält die Logik, und Slots ermöglichen flexible Inhalts-Einbettung.

Der Unterschied zu Twig-Macros: Macros sind reine Template-Funktionen ohne Zugang zum Twig-Kontext und ohne PHP-Backing. Sie können keine Services injizieren, keine Datenbank-Queries durchführen und keine PHP-Logik enthalten. TwigComponents sind vollständige PHP-Klassen, die Symfony-Services über Constructor Injection erhalten — mit demselben Dependency-Injection-Container wie Controller und Services. Eine Breadcrumb-Komponente kann den aktuellen Pfad direkt aus dem Request-Stack lesen. Eine Produktkarte kann ihren Preis mit dem Pricing-Service berechnen. Das macht TwigComponents zu echten Bausteinen einer skalierenden Frontend-Architektur in Symfony.

2. Installation und Ordnerstruktur

Die Installation von symfony/ux-twig-component erfolgt über Composer. Das Flex-Recipe registriert das Bundle und legt die Standardkonfiguration an. Komponenten-Templates liegen standardmäßig in templates/components/, PHP-Backing-Klassen in src/Twig/Components/. Die Konvention verknüpft Klasse und Template automatisch: Die Klasse App\Twig\Components\Alert verwendet das Template templates/components/Alert.html.twig. Custom-Pfade können in der Bundle-Konfiguration angepasst werden.

Für Namespace-Hierarchien innerhalb des Komponentensystems legt man Unterordner an: templates/components/Form/Input.html.twig entspricht dem Komponentennamen Form:Input. Das ermöglicht eine logische Gruppierung von Formular-Komponenten, Layout-Komponenten und UI-Komponenten. Die PHP-Klassen folgen derselben Hierarchie: App\Twig\Components\Form\Input. In großen Projekten mit einem vollständigen Design-System sind Unterordner unverzichtbar — ohne sie werden templates/components/ schnell zu einem unübersichtlichen Sammelsurium aus Dutzenden flachen Dateien.

<?php

declare(strict_types=1);

namespace App\Twig\Components;

use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;
use Symfony\UX\TwigComponent\Attribute\ExposeInTemplate;

/**
 * Alert component with configurable type and dismissible behavior.
 * Used as: <twig:Alert type="success" dismissible>Meldung</twig:Alert>
 */
#[AsTwigComponent]
final class Alert
{
    /**
     * The visual type of the alert: success, error, warning, or info.
     * Determines the background color and icon shown.
     */
    public string $type = 'info';

    /**
     * Whether the user can dismiss this alert via a close button.
     */
    public bool $dismissible = false;

    /**
     * Maps type to Tailwind CSS classes for background and border.
     * Exposed to the template via getTypeClasses().
     */
    #[ExposeInTemplate]
    public function getTypeClasses(): string
    {
        return match ($this->type) {
            'success' => 'bg-green-50 border-green-400 text-green-800',
            'error'   => 'bg-red-50 border-red-400 text-red-800',
            'warning' => 'bg-yellow-50 border-yellow-400 text-yellow-800',
            default   => 'bg-blue-50 border-blue-400 text-blue-800',
        };
    }
}

3. Anonymous Components: reine Template-Blöcke

Nicht jede TwigComponent braucht eine PHP-Klasse. Anonymous Components sind Twig-Templates in templates/components/, die keine Backing-Klasse haben. Sie empfangen Props über Twig-Variablen und eignen sich für rein strukturelle UI-Bausteine ohne Logik: Card-Container, Divider, Badge, Avatar. Der Aufruf erfolgt mit der HTML-ähnlichen Syntax: <twig:Card title="Produkt">Inhalt</twig:Card>. Diese Syntax ist für Teams, die aus React oder Vue kommen, intuitiv — Komponenten sehen aus wie HTML-Elemente und werden im Template eingesetzt.

Anonymous Components definieren ihre Props über den {% props %}-Tag am Anfang des Templates: {% props title, variant = 'default', class = '' %}. Übergebene Werte sind direkt als Twig-Variablen verfügbar. Unbekannte Props — Props, die nicht im {% props %}-Tag deklariert sind — landen in der speziellen Variable attributes, die alle nicht-deklarierten HTML-Attribute enthält. Das ermöglicht das Durchreichen von HTML-Attributen wie id, data-* und ARIA-Attributen an das Root-Element der Komponente, ohne sie explizit zu deklarieren. Diese Funktion ist vergleichbar mit $attrs in Vue oder ...rest in React-Komponenten.

4. Props: typsichere Eingabe in Komponenten

In PHP-Backing-Klassen werden Props als öffentliche Properties der Klasse definiert. PHP-Typsystem und Symfony-Validierung stehen vollständig zur Verfügung. Eine public string $type = 'info' ist ein String-Prop mit Standardwert. Eine public bool $dismissible = false ist ein Boolean-Prop. Das Symfony-Serializer-System kümmert sich um die Typkonvertierung — Strings aus dem Twig-Template werden automatisch in die korrekten PHP-Typen konvertiert. Für komplexe Typen wie Enums sind spezielle Hydratoren verfügbar.

PHP 8.1-Enums eignen sich ideal als Prop-Typen für TwigComponent. Ein AlertType-Enum mit Werten Success, Error, Warning und Info macht die erlaubten Prop-Werte im Code explizit — PHPStan und IDE-Autocompletion erkennen sofort, wenn ein ungültiger Wert übergeben wird. Das ist deutlich sicherer als ein String-Prop, bei dem Tippfehler erst zur Laufzeit auffallen. Die Hydration von String-Werten aus Twig-Templates auf Enum-Instanzen übernimmt das TwigComponent-Paket automatisch, wenn der Prop-Typ ein BackedEnum ist.

5. PHP-Backing-Klassen für Logik und Services

Der wesentliche Vorteil von PHP-Backing-Klassen in Symfony UX TwigComponent ist die vollständige Symfony-DI-Integration. Jede Klasse kann Services über Constructor Injection empfangen — genau wie ein Controller oder ein Repository. Eine Breadcrumb-Komponente injiziert den Router und den Request-Stack, um die aktuelle URL zu ermitteln und die Breadcrumb-Struktur automatisch aufzubauen. Eine Produktkarte injiziert einen Pricing-Service, um den nutzerabhängigen Preis direkt in der Komponente zu berechnen.

Methoden der Backing-Klasse, die mit #[ExposeInTemplate] markiert sind, stehen im Twig-Template direkt als Variablen zur Verfügung. Eine Methode getTypeClasses(): string ist im Template als { { typeClasses } } zugänglich — ohne expliziten Methodenaufruf. Das hält das Twig-Template sauber von PHP-Logik und ermöglicht Unit-Tests der Backing-Klasse ohne HTTP-Layer. Die Komponente kann isoliert getestet werden: Props setzen, Methoden aufrufen, Rückgabewerte prüfen. Das ist ein großer Vorteil gegenüber Twig-Macros oder komplexen include-Konstrukten, die nicht direkt testbar sind.

<?php
{# templates/components/Alert.html.twig #}
{# This template is automatically linked to App\Twig\Components\Alert #}
<div class="border-l-4 p-4 rounded { { typeClasses } }" role="alert">
  <div class="flex items-start gap-3">
    {# Icon based on type — rendered server-side, no JS needed #}
    {% if type == 'success' %}
      <svg class="w-5 h-5 mt-0.5 shrink-0" fill="currentColor" viewBox="0 0 20 20">
        <path fill-rule="evenodd" d="M10 18a8 8 0 100-16 8 8 0 000 16zm3.707-9.293a1 1 0 00-1.414-1.414L9 10.586 7.707 9.293a1 1 0 00-1.414 1.414l2 2a1 1 0 001.414 0l4-4z" clip-rule="evenodd"/>
      </svg>
    {% endif %}

    {# The default slot — content between <twig:Alert>...</twig:Alert> tags #}
    <div class="flex-1 text-sm font-medium">{ { content } }</div>

    {# Conditional dismiss button — only rendered when dismissible=true #}
    {% if dismissible %}
      <button type="button" class="ml-auto -mx-1.5 -my-1.5 rounded-lg p-1.5 inline-flex items-center justify-center h-8 w-8 opacity-70 hover:opacity-100">
        <span class="sr-only">Schließen</span>
        <svg class="w-3 h-3" fill="none" viewBox="0 0 14 14">
          <path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="m1 1 6 6m0 0 6 6M7 7l6-6M7 7l-6 6"/>
        </svg>
      </button>
    {% endif %}
  </div>
</div>

{# Usage in any Twig template:
   <twig:Alert type="success" :dismissible="true">
     Ihre Bestellung wurde erfolgreich aufgegeben!
   </twig:Alert>
   <twig:Alert type="error">
     Bitte überprüfen Sie Ihre Eingaben.
   </twig:Alert>
#}

6. Slots: flexible Inhalte in Komponenten einbetten

Slots sind benannte Bereiche innerhalb einer TwigComponent, die der aufrufende Code mit beliebigem Inhalt füllen kann. Der Standard-Slot ist das Twig-Konstrukt { { content } } — alles, was zwischen den öffnenden und schließenden Komponenten-Tags steht, wird als content verfügbar. Für Komponenten mit mehreren anpassbaren Bereichen — z. B. eine Karte mit Header, Body und Footer — definiert man benannte Slots mit dem {% block %}-Muster des TwigComponent-Slots-Systems.

Ein konkretes Beispiel: Eine Modal-Komponente hat einen Titel-Slot, einen Inhalts-Slot und einen Footer-Slot mit Aktions-Buttons. Der aufrufende Code füllt diese Slots mit beliebigem Twig-Inhalt, ohne die Grundstruktur des Modals zu kennen oder zu duplizieren. Das Modal-Template ist einmal definiert, alle Modalfenster in der Applikation sehen identisch aus und sind konsistent — Änderungen am Modal-Design müssen nur an einer Stelle gemacht werden. Dieses Muster entspricht dem Slot-Konzept aus Vue, Web Components und Svelte — in Symfony TwigComponent vollständig im Twig-Ökosystem.

7. Tailwind-CSS-Integration und Varianten

Tailwind CSS und Symfony UX TwigComponent passen sehr gut zusammen. Komponenten-Varianten werden über Tailwind-Klassen gesteuert, die PHP-Logik in der Backing-Klasse erzeugt. Das Klassenset für eine Schaltfläche mit Varianten primary, secondary und danger wird durch eine getClasses()-Methode berechnet, die den Prop-Wert in Tailwind-Klassen-Strings übersetzt. Das hält die Klassen-Logik aus dem Template heraus und macht sie unit-testbar.

Ein wichtiger Aspekt bei Tailwind und dynamischen Klassen: Tailwind scannt Quellcode nach Klassen-Strings zur Build-Zeit. Dynamisch zusammengesetzte Strings wie 'bg-' ~ color ~ '-500' werden nicht gefunden und aus dem CSS entfernt. Das korrekte Pattern ist daher, vollständige Klassen-Strings in PHP-Code oder Twig-Templates zu schreiben, nie zusammenzusetzen. In der Backing-Klasse verwendet man eine match-Expression, die vollständige Klassen-Strings zurückgibt: 'bg-green-500 text-white hover:bg-green-600'. Der Tailwind-Scanner findet diese vollständigen Strings und belässt sie im CSS-Output. Das ist dasselbe Muster, das aus der React-Tailwind-Integration bekannt ist — in TwigComponent ist es genau gleich.

8. Design-System mit TwigComponent aufbauen

Ein vollständiges Design-System mit Symfony UX TwigComponent besteht aus drei Schichten: Atom-Komponenten (Button, Badge, Icon, Input, Avatar), Molekül-Komponenten (AlertBanner, Card, FormGroup, Dropdown) und Organismus-Komponenten (Header, Sidebar, DataTable, Modal). Atom-Komponenten sind meist Anonymous Components ohne Backing-Klasse — sie sind reine Template-Blöcke mit Props. Molekül-Komponenten haben oft einfache Backing-Klassen, die Varianten-Logik enthalten. Organismus-Komponenten können Services injizieren und komplexe Daten aufbereiten.

Die konsistente Benennung folgt dem Muster DesignSystem:Atom:Button für den Komponentennamen, was im Twig-Template als <twig:DesignSystem:Atom:Button> erscheint. Das ist ausdrucksstärker als generische Namen und verhindert Namenskonflikte in großen Teams. Für Design-System-Dokumentation innerhalb des Projekts reicht ein einfaches Twig-Template, das alle Komponenten in ihren Varianten zeigt — Storybook-ähnlich, aber vollständig in Twig und PHP. Symfony UX TwigComponent macht die Wartung eines solchen Design-Systems zur PHP-Aufgabe ohne separates Frontend-Tooling.

9. TwigComponent vs. Twig-Include vs. Twig-Macro

Der direkte Vergleich der drei Ansätze für Twig-Wiederverwendung zeigt, wann welches Werkzeug die beste Wahl ist.

Für einfache Template-Partials ohne Logik ist include weiterhin legitim und ausreichend. Für wiederverwendbare UI-Blöcke mit Varianten und flexiblem Inhalt ist die Anonymous Component die richtige Wahl. Für Komponenten, die Services brauchen oder komplexe Ausgaben berechnen, ist die PHP-Backing-Klasse unverzichtbar. TwigComponent ersetzt Twig-Includes und Macros nicht vollständig — es ergänzt sie für den Bereich, wo eine Komponentenarchitektur wirklich gefragt ist.

10. Zusammenfassung

Symfony UX TwigComponent bringt echte Komponentenarchitektur in das Twig-Ökosystem. Anonymous Components ohne PHP-Backing eignen sich für reine Template-Blöcke mit Props und Slots. PHP-Backing-Klassen ermöglichen Service-Injection, Logik-Kapselung und Unit-Tests. Das Slot-System erlaubt flexible Inhalts-Einbettung für generische Layout-Komponenten. Tailwind-CSS-Varianten werden durch match-Expressions in der Backing-Klasse gesteuert — vollständige Klassen-Strings, die der Tailwind-Scanner findet.

Der größte Gewinn liegt in der Konsistenz und Wartbarkeit. Wenn zehn Templates denselben Alert-Block kopieren und das Design sich ändert, müssen zehn Stellen angepasst werden. Mit einem Alert-TwigComponent ist es eine. Neue Varianten, Barrierefreiheits-Verbesserungen und Design-Updates propagieren automatisch durch alle Stellen, die die Komponente verwenden. Kombiniert mit Live Component für reaktive Varianten und Turbo für Navigation, entsteht ein vollständiges, wartbares Frontend-System — vollständig in PHP und Twig ohne separates JavaScript-Framework.

11. FAQ: Symfony UX TwigComponent und wiederverwendbare Blöcke