Lernseite · Events, Dependency Injection und Erweiterung
TYPO3 erweitern, ohne den Core anzufassen
Hier lernst du die sauberen Wege, TYPO3 zu erweitern: Dependency Injection, Events, Hooks, Bedingungen und als letzten Ausweg die XCLASS.
Alle Beispiele gehören zur Extension my_extension, die Konferenzen verwaltet. Ein Importer holt Konferenzen aus einer fremden Quelle, ein Geocoder findet ihren Ort. Nach jedem Import informiert die Extension andere Extensions, und sie bietet eine eigene TypoScript-Bedingung an.
Erweitern statt ändern
Die Dateien von TYPO3 liegen im Ordner vendor, und den verwaltet Composer allein. Bei jedem Composer-Install oder Composer-Update schreibt er die Pakete neu, deine Änderung ist still verschwunden. Außerdem steht der Ordner meist in der .gitignore und kommt nie auf das Live-System.
Anpassungen gehören deshalb in eine eigene Extension. In dieser Reihenfolge empfiehlt TYPO3 die Erweiterungspunkte:
- PSR-14-Events sind der wichtigste Weg.
- Hooks sind ältere Erweiterungspunkte. Neue kommen nicht mehr hinzu.
- Konfigurationspunkte wie User-Funktionen im TCA oder ein eigener Service per Dependency Injection.
- Die XCLASS ersetzt eine ganze Klasse und ist der letzte Ausweg.
Nicht jede öffentliche Core-Methode ist ein offizieller Erweiterungspunkt. Was stabil bleibt, regeln Core-API und Deprecation-Policy. Was mit @internal markiert ist, gehört nicht dazu.
Dahinter stehen zwei Prinzipien. Lose Kopplung heißt: Zwei Teile kennen voneinander möglichst wenig, etwa nur eine Schnittstelle. Dann lässt sich jeder Teil einzeln ändern, testen und austauschen. Interfaces, Events und Dependency Injection helfen dabei, statische Aufrufe und globale Variablen schaden.
Inversion of Control heißt: Das Framework ruft deinen Code an festen Stellen auf, nicht umgekehrt. Das ist das Hollywood-Prinzip: Ruf uns nicht an, wir rufen dich an. In TYPO3 erzeugt der Container deine Klassen, der Event-Dispatcher ruft deine Listener auf und Extbase deine Controller-Action.
Auf Ereignisse reagieren kann Software auf mehrere Arten: mit dem Observer-Muster, mit Dispatcher und Listenern, mit Callbacks und Hooks oder zwischen Systemen mit Message Queues.
Dependency Injection und der Container
Bei Dependency Injection baut eine Klasse ihre Abhängigkeiten nicht selbst, sie bekommt sie fertig übergeben. Das erledigt der DI-Container. Die Kontrolle über das Erzeugen liegt also bei ihm.
TYPO3 nutzt den Container von Symfony. Er erfüllt PSR-11, und dieser Standard kennt nur zwei Methoden: get() holt einen Service, has() fragt, ob es ihn gibt.
Empfohlen ist Konstruktor-Injection. Du schreibst die Abhängigkeit als Parameter in den Konstruktor, und der Container übergibt anhand des Typs die passende Instanz. Das nennt man Autowiring.
final class ConferenceImporter
{
public function __construct(
private readonly ConferenceRepository $conferenceRepository,
) {}
}Die Vorteile: Die Abhängigkeiten stehen sichtbar in der Signatur. Im Test übergibst du ein Test-Double. Die Implementierung lässt sich per Konfiguration austauschen. Und die Klasse kennt nur Schnittstellen, nicht die Erzeugung ihrer Abhängigkeiten. Zirkuläre Abhängigkeiten löst Dependency Injection nicht, sie führen zu Fehlern im Container.
Die zweite Form ist die Methoden-Injection über öffentliche Methoden, deren Name mit inject beginnt. Sie ist für Basisklassen gedacht, etwa den ActionController von Extbase. So haben deine Controller einen eigenen Konstruktor, ohne den der Elternklasse zu kennen. Und der Core kann Abhängigkeiten ergänzen, ohne deine Klassen zu brechen. Weitere Formen unterstützt TYPO3 nicht.
Unterscheide Services und Datenobjekte:
- Ein Service kommt aus dem Container, etwa ein Controller, Repository, Listener oder Logger. Services sind standardmäßig geteilt und sollen darum keinen Zustand speichern.
- Ein Datenobjekt wie ein Domain-Model, ein Wertobjekt oder ein Event entsteht mit
newoder aus der Datenbank. Es bekommt keine Injection.
GeneralUtility::makeInstance() brauchst du nur noch, wo Dependency Injection nicht geht. Holt es einen Service aus dem Container, muss der Service öffentlich sein. Bei Konstruktor-Injection spielt das keine Rolle.
Die Datei Services.yaml
Wie der Container deine Klassen behandelt, legt Configuration/Services.yaml fest, alternativ eine Services.php. Ohne sie werden Konstruktor-Abhängigkeiten nicht aufgelöst. Die composer.json sorgt nur dafür, dass PHP die Klassen findet.
services:
_defaults:
autowire: true
autoconfigure: true
public: false
MyVendor\MyExtension\:
resource: '../Classes/*'
exclude: '../Classes/Domain/Model/*'- autowire ermittelt Abhängigkeiten aus den Typen im Konstruktor.
- autoconfigure vergibt Tags anhand von Interfaces, Basisklassen oder Attributen. So wird ein Listener mit
AsEventListeneroder ein Befehl mitAsCommandohne weiteren Eintrag registriert. - public false spart Leistung. Einzelne Services machst du mit dem Attribut
Autoconfigureund der Option public öffentlich. - resource bestimmt, welche Klassen der Container kennt.
Das geht mit dem Befehl cache:flush oder im Install Tool unter System, Maintenance, Flush Caches. Der Knopf in der Backend-Toolbar leert den Container nur im Context Development, nicht in Production. Hat eine kaputte Services.yaml Frontend und Backend lahmgelegt, heilt sich das nicht von selbst.
Zwei Implementierungen: Der Controller verlangt ein GeocoderInterface. Bei genau einer Implementierung verknüpft Symfony sie selbst. Wir haben aber zwei, den OpenStreetMapGeocoder und den GoogleGeocoder, und der Container meldet einen Fehler. Die Lösung ist ein Alias: das Attribut AsAlias mit dem Interface an der gewünschten Klasse oder ein Eintrag in der Services.yaml.
MyVendor\MyExtension\Geocoder\GeocoderInterface:
'@MyVendor\MyExtension\Geocoder\OpenStreetMapGeocoder'Weitere Werkzeuge aus Symfony:
- Umgebungsvariablen: Das Attribut
Autowiremit der Option env oder ein env-Platzhalter in der Services.yaml. Der Wert wird zur Laufzeit gelesen, ohne Cache-Leeren. - Sammlungen:
AutoconfigureTagamExporterInterfacemarkiert jeden Exporter,AutowireIteratorim Konstruktor desExportServicesammelt sie alle. - Decorator: Eine Klasse mit
AsDecoratorerhält den Original-Service überAutowireDecoratedund reicht die Aufrufe weiter, etwa um davor und danach zu protokollieren. Alle bekommen dann den Decorator. Eine XCLASS arbeitet dagegen über Vererbung.
public function __construct(
#[Autowire(env: 'MYEXT_API_URL')] private readonly string $apiUrl,
#[AutowireIterator('myext.exporter')] private readonly iterable $exporters,
) {}Fehlt eine Abhängigkeit? Prüfe, ob die Services.yaml autowire und die passende resource enthält, ob die Caches geleert sind und ob es für ein Interface eine Implementierung oder einen Alias gibt.
Wie PSR-14-Events funktionieren
PSR-14 ist ein PHP-Standard für Event-Dispatcher. An festen Stellen erzeugt der Core ein Event-Objekt und gibt es an alle Listener weiter. Keine Core-Datei wird angefasst, darum übersteht die Anpassung jedes Update.
PSR-14 kennt fünf Bausteine:
- Das Event ist ein einfaches Objekt mit den Daten. Setter gibt es nur für das, was Listener ändern dürfen.
- Der Listener ist die Klasse, die reagiert. Wer auf ein Event hört, schreibt einen Listener.
- Der Emitter ist der Code, der das Event auslöst.
- Der Dispatcher ruft die Listener nacheinander auf.
- Der Listener Provider liefert ihm die Listener zu einem Event.
Auf ein Event dürfen beliebig viele Listener reagieren, auch aus verschiedenen Extensions. Ein zweiter ersetzt keinen ersten. Neue Reaktionen kommen hinzu, ohne den Auslöser zu ändern.
Die Namen der Core-Events helfen: Before kommt vor einem Vorgang, After danach, und Modify bietet an, ein Ergebnis zu ändern. Eine Priorität steckt nicht im Namen.
Für Core-Events gilt die Deprecation-Policy, nur ihre Konstruktor-Argumente können sich ändern. Eine gemeinsame Basisklasse brauchen Events nicht.
Einen Listener schreiben
Am einfachsten setzt du das Attribut AsEventListener an die Klasse. Die Methode __invoke() bekommt das Event, und TYPO3 erkennt es am Typ des Parameters.
#[AsEventListener(identifier: 'my-extension/replace-placeholder')]
final readonly class ReplacePlaceholderListener
{
public function __invoke(AfterCacheableContentIsGeneratedEvent $event): void
{
$event->setContent(str_replace('###YEAR###', date('Y'), $event->getContent()));
}
}Das Event kommt nach dem Rendern des cachebaren Teils der Seite, die Änderung landet mit im Cache. Mit disableCaching() könnte der Listener das Speichern verhindern.
Das Attribut kennt fünf Optionen:
- identifier ist die eindeutige Kennung.
- before und after nennen die Kennung eines anderen Listeners und legen so die Reihenfolge fest. Eine Priorität als Zahl gibt es nicht.
- event nennt die Event-Klasse, falls der Parametertyp nicht reicht.
- method nennt eine andere Methode statt
__invoke().
Das Attribut darf auch an mehreren Methoden einer Klasse stehen, jede wird ein eigener Listener. Ohne die Option event zählt der Typ des ersten Parameters, ein Union-Typ meldet die Methode für mehrere Events an. Dafür muss die Klasse autowired sein. Statt des Attributs geht auch das Tag event.listener in der Services.yaml.
Fremden Listener ersetzen: Registriere deinen Listener mit genau der Kennung des fremden Listeners. Dann läuft nur noch deiner. Trage die fremde Extension als Abhängigkeit in deine composer.json ein, damit deine Registrierung später geladen wird.
Der Dispatcher ist eine normale PSR-14-Implementierung. Du fängst also auch Events aus fremden PHP-Bibliotheken ab.
Ein paar Core-Events:
ModifyUrlForCanonicalTagEventändert die URL im Canonical-Tag von EXT:seo mitsetUrl(). Die MetaTag-API hilft hier nicht, denn der Canonical ist ein Link-Element.BeforeMailerSentMessageEventkommt vor dem Versand jeder Mail, etwa für einen zusätzlichen Header. Das After-Event informiert erst danach.ModifyButtonBarEventergänzt Buttons in der Kopfleiste der Backend-Module.
Eigene Events auslösen
Nach jedem Import soll my_extension andere Extensions informieren, ohne sie zu kennen. Ein direkter Aufruf oder eine XCLASS würde beide fest koppeln. Also löst der Importer ein eigenes Event aus. Wer will, registriert einen Listener darauf.
- Lege die Event-Klasse in
Classes/Eventan, ihr Name endet auf Event. - Biete nur die Daten an, die Listener brauchen. Setter nur für Werte, die sie ändern dürfen.
- Hole das
EventDispatcherInterfaceaus dem Namensraum Psr per Dependency Injection. In Extbase-Controllern ist es schon da. - Löse das Event mit
dispatch()aus. Du bekommst dasselbe Objekt zurück, vielleicht von Listenern geändert.
$event = $this->eventDispatcher->dispatch(
new AfterConferencesImportedEvent($conferences)
);
$conferences = $event->getConferences();Gib dem Event nie den ganzen Controller mit, zu viel Kontext koppelt die Listener an deine Interna. Setter braucht ein Event nur, wenn Listener Daten anpassen sollen, die der Emitter danach weiterverwendet. Für reine Benachrichtigungen reicht ein unveränderliches Event.
PSR-14 beschreibt vier Anwendungsfälle: Benachrichtigen, Anreichern oder Verändern eines Objekts, Sammeln von Beiträgen mehrerer Listener und die alternative Kette, in der ein Listener die weitere Verarbeitung beendet.
Für den letzten Fall setzt das Event das StoppableEventInterface um. Der Dispatcher fragt vor jedem Listener isPropagationStopped() ab und hört auf, sobald wahr zurückkommt.
Wenn ein Listener schweigt
- Das Modul System, Configuration zeigt unter Event Listeners (PSR-14) alle registrierten Listener mit Kennung und Reihenfolge. Es stammt aus der Extension lowlevel und ist nur für Administratoren sichtbar.
- Das Admin Panel zeigt unter Debug, Events, welche Events ein Frontend-Request tatsächlich ausgelöst hat.
Seit TYPO3 14 heißt die frühere Gruppe Admin Tools jetzt System, die frühere Gruppe System heißt Administration.
Hooks, TCA-Funktionen und XCLASS
Hooks sind ältere Stellen, an denen der Core eingetragene Funktionen aufruft. Du meldest sie in der ext_localconf.php unter den SC_OPTIONS der globalen Konfiguration an. Sie werden nach und nach durch Events ersetzt, in TYPO3 14 etwa alle Hooks des Form Frameworks. Für das Speichern im DataHandler ist der Hook weiter üblich.
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_tcemain.php']['processDatamapClass'][] = MyHook::class;Es gibt zwei Arten:
- Objekt-Hooks: Der Core erzeugt die Klasse mit
GeneralUtility::makeInstance()und ruft eine festgelegte Methode auf, wie beim DataHandler. - Funktions-Hooks: Eingetragen ist Klasse und Methode. Der Core ruft sie mit
GeneralUtility::callUserFunction()auf, mit einem Parameter-Array und dem aufrufenden Objekt.
User-Funktionen im TCA sind ein weiterer Erweiterungspunkt. Mit itemsProcFunc holt ein Auswahlfeld seine Optionen zur Laufzeit, etwa aus einer API. So bleibt das TCA statisch. Ähnliches gibt es für Anzeigebedingungen und die postModifiers von Slug-Feldern.
'itemsProcFunc' => MyItems::class . '->getItems',Die XCLASS ersetzt eine Klasse vollständig. Deine Klasse erweitert das Original und überschreibt einzelne Methoden. Wo TYPO3 das Original erzeugen würde, erzeugt es deine Klasse. Du meldest sie in der ext_localconf.php an.
$GLOBALS['TYPO3_CONF_VARS']['SYS']['Objects'][Original::class] = [
'className' => MyXclass::class,
];Die Grenzen der XCLASS:
- Sie wirkt nur, wenn die Klasse über
GeneralUtility::makeInstance()oder den Container entsteht. - Für statische, abstrakte oder finale Klassen geht sie nicht, private Methoden lassen sich nicht überschreiben.
- Je Originalklasse ist nur eine XCLASS aktiv.
- Sie hängt an den Interna des Originals und kann bei jedem Update brechen.
Bei Extbase-Controllern muss die XCLASS selbst ein Service im Container sein. Und PHP vererbt keine Attribute. Überschreibst du eine Action mit Authorize oder RateLimit, wiederholst du diese Attribute und die an den Parametern. Sonst ist die Action ungeschützt.
Bedingungen, Feature-Toggles und die Registry
Die Symfony Expression Language wertet Bedingungen aus: in TypoScript und TSconfig, in den Base Variants der Site-Konfiguration und seit TYPO3 14 in der Option limitToPages von Route Enhancern. Fluid nutzt sie nicht, f:if hat eine eigene Syntax.
Variablen haben kein Dollarzeichen, und es gibt keine Kontrollstrukturen. Verknüpft wird mit and, or und not. Dazu kommen in für Listen, matches für reguläre Ausdrücke und die Tilde zum Verketten. Ein Ausdruck kann beliebige Werte liefern, TypoScript macht daraus wahr oder falsch.
[frontend.user.isLoggedIn]
[12 in tree.rootLineIds]
[tree.pagelayout == "pagets__home"]
[3 in frontend.user.userGroupIds]
[applicationContext matches "/^Development/"]
[traverse(request.getQueryParams(), 'tx_news_pi1/news') > 0]- Die uid in der Variable page trifft nur die Seite selbst, die Rootline den ganzen Teilbaum.
- Das Feld backend_layout ist bei erbenden Unterseiten leer, tree.pagelayout enthält das geltende Layout.
- Ein direkter Zugriff auf ein fehlendes Array-Element bricht ab,
traverse()liefert dann einen leeren Text. - Zwei Gleichheitszeichen treffen nur den exakten Context,
matchesauch Unterkontexte. - Alte Schreibweisen wie loginUser oder globalVar gibt es seit TYPO3 10 nicht mehr.
Eigene Funktionen: Für eine Bedingung conferenceIsRunning() trägst du in Configuration/ExpressionLanguage.php einen Provider für den Kontext typoscript ein. Er nennt einen Funktions-Provider, der die Funktionen mit getFunctions() liefert. Aktive Provider zeigt System, Configuration.
Feature-Toggles schalten eine neue Umsetzung neben der alten ein. Sie gelten systemweit und stehen in der globalen Konfiguration unter SYS, features. Core-Toggles schaltest du im Modul System, Settings unter Feature Toggles. Eigene Toggles erscheinen dort nicht. Ihren Standardwert setzt deine Extension in der ext_localconf.php.
$GLOBALS['TYPO3_CONF_VARS']['SYS']['features']['myExtensionNewList'] ??= true;In PHP fragst du isFeatureEnabled() an der Klasse Features ab. In TypoScript gibt es die Funktion feature(), in Fluid den ViewHelper f:feature. Der Name beginnt mit dem Extension-Namen und enthält weder enable noch disable noch eine Verneinung.
Das Registry-Muster ist eine zentrale Stelle, an der Werte unter einem Schlüssel liegen und von überall abrufbar sind. Beispiele sind die IconRegistry und die System-Registry. Der Nachteil ist eine versteckte, globale Abhängigkeit. Die Klasse Registry speichert Paare aus Schlüssel und Wert je Namensraum in der Tabelle sys_registry. Die Methode get() nimmt einen Standardwert, falls nichts da ist. Sie passt für Kleinigkeiten wie den Zeitpunkt des letzten Imports, nicht für Sitzungs- oder Cachedaten.
Das Wichtigste in Kürze
- Ändere nie den Ordner vendor. Die XCLASS ist der letzte Ausweg.
- Konstruktor-Injection ist der Standard. Services sind geteilt, Models und Events entstehen mit new.
- Nach Änderungen an der Services.yaml immer die Caches leeren.
- Zwei Implementierungen eines Interfaces brauchen einen Alias.
- Ein Listener bekommt das Attribut AsEventListener, die Reihenfolge regeln before und after.
- Eigene Events löst du mit dispatch aus.
- Listener zeigt System, Configuration, ausgelöste Events das Admin Panel.
Begriffe
- Autowiring
- Der Container erkennt Abhängigkeiten an den Typen im Konstruktor.
- Decorator
- Klasse, die einen Service umhüllt und seine Aufrufe weiterreicht.
- Emitter
- Code, der ein Event an den Dispatcher übergibt.
- Hook
- Älterer Erweiterungspunkt, der eingetragene Klassen oder Funktionen aufruft.
- Inversion of Control
- Das Framework ruft deinen Code auf, nicht umgekehrt.
- Listener Provider
- Liefert dem Dispatcher alle Listener zu einem Event.
- XCLASS
- Eigene Klasse, die TYPO3 an Stelle einer Originalklasse erzeugt.