Was sind Twig Hooks?

Twig Hooks sind ein konfigurierbares Layoutsystem für Symfony und Sylius, das Template Overrides durch deklarative Hook Punkte ersetzt. Statt ganze Templates zu kopieren und in templates/bundles/ zu überschreiben, definieren Entwickler benannte Einfügepunkte direkt in Twig Templates und registrieren Inhalte per YAML Konfiguration. Das Ergebnis sind modulare, wartbare und update sichere Layouts.

Das Paket sylius/twig-hooks gehört zum Sylius Stack und funktioniert als eigenständige Symfony Komponente. Es unterstützt drei Arten von Hookables: klassische Twig Templates, Twig Components aus dem Symfony UX Ökosystem und Symfony Live Components für interaktive Elemente. Damit löst es die älteren Systeme wie Sonata Block Events und Sylius Template Events vollständig ab.

Für PHP Entwickler, die komplexe Symfony Anwendungen oder Sylius Shops betreiben, bieten Twig Hooks entscheidende Vorteile: Plugin Kompatibilität bleibt bei Updates erhalten, mehrere Plugins können dieselbe Stelle erweitern ohne Konflikte, und die Reihenfolge der Inhalte lässt sich über ein Priority System flexibel steuern. Wer seine Template Architektur modernisieren möchte, findet in Twig Hooks den aktuellen Standard für 2026.

Das Grundprinzip von Twig Hooks basiert auf zwei Konzepten: Hooks und Hookables. Ein Hook ist ein benannter Einfügepunkt innerhalb eines Twig Templates. Er wird mit dem Tag {% hook 'hook_name' %} definiert und markiert eine Stelle, an der externe Inhalte eingefügt werden können. Ein Hookable ist der konkrete Inhalt, der in einen Hook geladen wird, also ein Template, eine Twig Component oder eine Live Component.

Die Zuordnung zwischen Hooks und Hookables erfolgt über eine YAML Konfiguration unter config/packages/twig_hooks.yaml. Jeder Hookable erhält einen eindeutigen Namen, einen Template Pfad oder Component Key, und optional eine Priority, die die Reihenfolge innerhalb des Hooks bestimmt. Je höher die Priority, desto früher wird der Hookable gerendert. Standardmäßig ist die Priority 0.

Hooks sind hierarchisch organisiert und bilden eine Baumstruktur. Das bedeutet: ein Hookable kann selbst wieder einen Hook enthalten, sodass verschachtelte Layouts entstehen. Dieses System ermöglicht eine klare Trennung zwischen Struktur (Hooks) und Inhalt (Hookables), was die Wartbarkeit großer Symfony Projekte deutlich verbessert.

Twig Hooks lässt sich als eigenständiges Composer Paket installieren. Es setzt PHP 8.2 oder höher sowie Symfony 6.4 oder 7.x voraus. Die Installation erfolgt über Composer:

Nach der Installation wird die Konfiguration in einer YAML Datei unter config/packages/ angelegt. Der grundlegende Aufbau folgt immer dem gleichen Muster: unter dem Schlüssel sylius_twig_hooks.hooks werden Hook Namen definiert, darunter die zugehörigen Hookables mit ihren Eigenschaften.

Im Twig Template wird der Hook dann mit einem einzigen Tag eingefügt. Alle registrierten Hookables werden automatisch gerendert, sortiert nach Priority:

Twig Hooks unterstützen drei verschiedene Typen von Hookables, die jeweils unterschiedliche Anforderungen abdecken:

Template Hookables sind die einfachste Variante. Sie verweisen auf eine Twig Datei, die an der Hook Position gerendert wird. Context Daten werden über die context Eigenschaft in der YAML Konfiguration oder über das with Keyword im Hook Tag übergeben. Im Template stehen sie über hookable_metadata.context oder die Funktion get_hookable_context() zur Verfügung.

Component Hookables nutzen Twig Components aus dem Symfony UX Ökosystem. Statt eines Template Pfads wird ein Component Key angegeben, und Props werden direkt in der Konfiguration definiert. Das ist ideal für Hookables mit komplexer Logik, weil die Business Logik in einer PHP Klasse liegt und nicht im Template.

Live Component Hookables erweitern das Konzept um interaktive Elemente mit Symfony UX Live Components. Sie reagieren auf Benutzeraktionen ohne vollständige Seitenneulads. Das ist besonders relevant für E Commerce Szenarien wie dynamische Filter, Warenkörbe oder Echtzeit Suchfelder in Sylius Shops.

Twig Hooks bieten ein Autoprefixing Feature, das bei der Entwicklung größerer Projekte oder Bundles für Struktur sorgt. Wenn ein Hookable selbst einen Hook enthält, wird der Name des übergeordneten Hooks automatisch als Präfix vorangestellt. Aus einem Hook {% hook 'form' %} innerhalb eines Hookables unter app.product.create wird automatisch app.product.create.form.

Dieses Verhalten ermöglicht Composable Layouts mit vorhersagbarer Struktur. Entwickler können generische Layouts definieren, etwa für alle Create Formulare, und diese dann für spezifische Entitäten gezielt überschreiben. Dabei nutzt das System ein Multi Hook Feature: ein einzelner Hook kann mehrere Namen tragen, wobei die früheren Namen eine höhere Priorität haben.

In der Praxis bedeutet das: eine einzige Template Basis für wiederkehrende UI Muster, mit gezielten Anpassungen pro Seite. Das reduziert Codeduplizierung erheblich und macht Layouts auch in großen Sylius Projekten mit vielen Entitäten beherrschbar. Für Teams, die mit mehreren Entwicklern an einem Projekt arbeiten, ist diese Vorhersagbarkeit ein entscheidender Vorteil.

Der klassische Weg zur Template Anpassung in Symfony besteht darin, die Original Datei nach templates/bundles/ zu kopieren und dort zu modifizieren. Dieser Ansatz hat mehrere Nachteile: bei jedem Update des Bundles müssen die kopierten Templates manuell abgeglichen werden. Wenn mehrere Plugins dasselbe Template überschreiben, entstehen Konflikte, die nur schwer aufzulösen sind.

Twig Hooks lösen diese Probleme grundlegend. Statt das gesamte Template zu ersetzen, fügen Entwickler Inhalte an definierten Stellen ein, entfernen bestehende Hookables durch enabled: false oder ändern die Reihenfolge über die Priority. Mehrere Plugins können denselben Hook erweitern, ohne sich gegenseitig zu beeinflussen. Updates des Core Templates bleiben wirksam, weil die Struktur unangetastet bleibt.

Für Sylius Projekte ist dieser Unterschied besonders relevant: In Sylius 2.0 ersetzen Twig Hooks die bisherigen Template Events vollständig. Wer von Sylius 1.x auf 2.0 migriert, muss bestehende Template Overrides in die neue Hook basierte Architektur überführen. NCA unterstützt bei dieser Migration mit Erfahrung aus zahlreichen Rector gestützten Refactoring Projekten.

Never Code Alone begleitet PHP Teams bei der Migration von Legacy Template Overrides zu modernen Hook basierten Architekturen. Ob Sylius 2.0 Upgrade, Symfony UX Integration oder die Entwicklung eigener Bundle Plugins mit Twig Hooks: unsere Consultants bringen die praktische Erfahrung mit, die den Unterschied zwischen einem sauberen Refactoring und monatelangem Debugging macht.

Gerade bei gewachsenen Sylius Shops mit vielen individuellen Anpassungen ist der Umstieg auf Twig Hooks eine strategische Investition. Die alte Methode über templates/bundles/ erzeugt technische Schulden, die mit jedem Core Update wachsen. Twig Hooks eliminieren diese Abhängigkeit und machen Projekte langfristig wartbar. Für eine kostenlose Erstberatung zur Template Modernisierung erreichen Sie uns unter roland@nevercodealone.de oder telefonisch unter +49 176 24747727.

Die wichtigsten Fragen und Antworten rund um Twig Hooks, Installation, Konfiguration und den Einsatz in Symfony und Sylius Projekten.