Lernseite · Events, Dependency Injection und Erweiterung

TYPO3 erweitern, ohne den Core anzufassen

Stand 15. November 2026 · TYPO3 14.3 LTS · ca. 18 Min. Lesezeit

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,
    ) {}
}
Codebeispiel. Der Importer bekommt das ConferenceRepository über seinen Konstruktor.

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 new oder 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/*'
YAML-Beispiel. Voreingestellt sind autowire, autoconfigure und public false. Alle Klassen aus dem Ordner Classes werden Services, außer den Domain-Models.
  • autowire ermittelt Abhängigkeiten aus den Typen im Konstruktor.
  • autoconfigure vergibt Tags anhand von Interfaces, Basisklassen oder Attributen. So wird ein Listener mit AsEventListener oder ein Befehl mit AsCommand ohne weiteren Eintrag registriert.
  • public false spart Leistung. Einzelne Services machst du mit dem Attribut Autoconfigure und 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'
YAML-Beispiel. Das GeocoderInterface verweist als Alias auf den OpenStreetMapGeocoder.

Weitere Werkzeuge aus Symfony:

  • Umgebungsvariablen: Das Attribut Autowire mit der Option env oder ein env-Platzhalter in der Services.yaml. Der Wert wird zur Laufzeit gelesen, ohne Cache-Leeren.
  • Sammlungen: AutoconfigureTag am ExporterInterface markiert jeden Exporter, AutowireIterator im Konstruktor des ExportService sammelt sie alle.
  • Decorator: Eine Klasse mit AsDecorator erhält den Original-Service über AutowireDecorated und 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,
) {}
Codebeispiel. Der Konstruktor bekommt die API-Adresse aus einer Umgebungsvariable und alle Services mit dem Tag myext.exporter.

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.
Emitter, etwa der Importer dispatch($event) Dispatcher EventDispatcherInterface Listener Provider liefert alle Listener zum Event Dispatcher ruft sie nacheinander auf Listener 1 my_extension Listener 2 seo Listener 3 andere Dasselbe Event zurück Emitter liest die geänderten Werte Reihenfolge nur über before und after
Ein Event, beliebig viele Listener. Der Emitter kennt keinen von ihnen.

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()));
    }
}
Codebeispiel. Ein Listener mit dem Attribut AsEventListener und einer eindeutigen Kennung. Seine Methode invoke bekommt das AfterCacheableContentIsGeneratedEvent, liest den Inhalt der Seite und schreibt ihn mit einem ersetzten Platzhalter zurück.

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 mit setUrl(). Die MetaTag-API hilft hier nicht, denn der Canonical ist ein Link-Element.
  • BeforeMailerSentMessageEvent kommt vor dem Versand jeder Mail, etwa für einen zusätzlichen Header. Das After-Event informiert erst danach.
  • ModifyButtonBarEvent ergä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.

  1. Lege die Event-Klasse in Classes/Event an, ihr Name endet auf Event.
  2. Biete nur die Daten an, die Listener brauchen. Setter nur für Werte, die sie ändern dürfen.
  3. Hole das EventDispatcherInterface aus dem Namensraum Psr per Dependency Injection. In Extbase-Controllern ist es schon da.
  4. 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();
Codebeispiel. Der Importer übergibt ein neues AfterConferencesImportedEvent an dispatch und liest danach die Konferenzen aus dem zurückgegebenen Event.

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;
Codebeispiel. Die Klasse MyHook wird in die Liste processDatamapClass des DataHandlers eingetragen. Er ruft dann bei jeder Speicherung ihre Methoden auf.

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',
TCA-Ausschnitt. itemsProcFunc verweist auf die Methode getItems der Klasse MyItems.

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,
];
Codebeispiel. Unter SYS, Objects wird für die Originalklasse unter dem Schlüssel className die eigene Klasse eingetragen.
Gibt es ein passendes Event? ja Listener AsEventListener nein Gibt es einen Hook oder eine TCA-Funktion? ja Hook nutzen itemsProcFunc, … nein Kommt die Klasse als Service aus dem Container? ja Alias oder Decorator nein XCLASS Letzter Ausweg: nur eine XCLASS je Klasse, bricht leicht bei Updates Von oben nach unten: erst Event, zuletzt XCLASS
Erst das Event, zuletzt die XCLASS.

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]
Sechs TypoScript-Bedingungen: angemeldeter Frontend-Benutzer. Seite 12 mit allen Unterseiten. Backend-Layout home, auch geerbt. Benutzergruppe 3. Context Development mit Unterkontexten. Eine News-Nummer in der URL, sicher gelesen mit traverse.
  • 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, matches auch 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;
Codebeispiel aus der ext_localconf.php. Der Toggle myExtensionNewList bekommt den Standardwert true, falls noch kein Wert gesetzt ist.

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.

Stand: 15. November 2026 (TYPO3 14.3 LTS)

Quellen:

  • TYPO3 Explained 14.3, Kapitel Dependency Injection, Events (PSR-14), Hooks, XCLASS, Symfony Expression Language, Feature Toggles, System Registry
  • PHP-FIG, PSR-11 Container Interface und PSR-14 Event Dispatcher
  • Symfony-Dokumentation DependencyInjection (Attribute für Alias, Decorator, Tags und Umgebungsvariablen)
  • Quellcode TYPO3 14.3 (typo3/cms-core), geprüft für AsEventListener, ListenerProviderPass, DataHandler (Cache leeren) und ExpressionLanguage
  • Lernzielkatalog TYPO3 CMS Certified Developer 14 LTS, Bereiche Kernkonzepte und Erweiterbarkeit

Diese Lernseite ist mit KI erstellt und gegen die Quellen geprüft.

Zertifikate & Prüfungen

Welche Prüfung kommt als Nächstes?

51 Prüfungen kannst du schon üben, über 16 stimmst du gerade ab. Sieh dir alle Zertifikate mit offiziellen Infos an, gib deine Stimme ab oder schlag deine Prüfung vor.

Zur Zertifikatsübersicht