Lernseite · Sites, Routing und Request
Vom Aufruf zur Seite: Sites, Routing und Request in TYPO3
Bevor TYPO3 HTML rendert, entscheidet es: welche Site, welche Sprache, welche Seite und welche Plugin-Argumente. Auf dieser Seite folgst du diesem Weg, von den Middlewares über die Site-Konfiguration und die Route Enhancer bis zum cHash und zu den Sessions.
Vom Aufruf zur Antwort
Unser Beispiel ist die Site main mit Deutsch und Englisch. Die Extension my_extension bringt das Plugin ConferenceList mit, eine Liste und eine Detailansicht von Konferenzen. Ein Besucher ruft diese Adresse auf:
https://example.org/de/konferenzen/typo3-days-2026.htmlDer Bootstrap richtet die Umgebung ein, danach übernimmt eine Application. Der Core hat vier davon: für das Frontend, für das Backend samt Ajax, für die Kommandozeile und für das Install Tool.
TYPO3\CMS\Frontend\Http\Application
TYPO3\CMS\Backend\Http\Application
TYPO3\CMS\Core\Console\CommandApplication
TYPO3\CMS\Install\Http\ApplicationExtbase hat keine eigene Application. Es startet erst, wenn TYPO3 beim Rendern auf ein Plugin trifft.
Danach läuft der Request durch einen Stapel von Middlewares nach PSR-15. Jede Middleware kann den Request verändern, ihn weiterreichen oder selbst antworten, etwa mit einer Weiterleitung. Am Ende erzeugt der Request Handler die Seite. Die Response läuft rückwärts zurück, und jede Middleware kann sie noch anpassen.
Eine eigene Middleware
Unsere Extension ermittelt für jeden Besucher eine Region. Die Middleware implementiert das MiddlewareInterface mit der Methode process().
public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
{
$region = $request->getQueryParams()['region'] ?? 'de';
$request = $request->withAttribute('myext.region', $region);
return $handler->handle($request);
}PSR-7-Requests sind unveränderlich. withAttribute() liefert eine geänderte Kopie. Ohne Zuweisung reichst du den alten Request weiter, und das Attribut fehlt im Controller.
Seit TYPO3 14 gleicht der Core die Superglobals für GET und POST nicht mehr mit dem Request ab. Lies Parameter darum mit getQueryParams() aus dem übergebenen Request. Auch die globale Request-Variable ist in frühen Middlewares noch nicht gesetzt. Für eine eigene Antwort, etwa JSON, holst du per Dependency Injection die PSR-17-Factories ResponseFactoryInterface und StreamFactoryInterface. Die Response-Klassen des Core sind keine öffentliche API.
Anmelden musst du die Middleware in Configuration/RequestMiddlewares.php. Die Services.yaml regelt nur die Dependency Injection.
return [
'frontend' => [
'my-extension/region' => [
'target' => \MyVendor\MyExtension\Middleware\RegionResolver::class,
'after' => ['typo3/cms-frontend/site'],
'before' => ['typo3/cms-frontend/page-resolver'],
],
],
];Die erste Ebene ist der Stapel, frontend oder backend. Je Middleware gibt es die Schlüssel target, before, after und disabled. Eine Priorität gibt es nicht. Ohne before und after landet die Middleware an einer beliebigen Stelle. Das Attribut site setzt erst der Site Resolver mit dem Identifier typo3/cms-frontend/site. Wer es lesen will, muss mit after hinter ihm stehen.
Die sortierte Liste siehst du im Modul „System“, „Configuration“ der Extension lowlevel, Eintrag „HTTP Middlewares (PSR-15)“. Willst du eine Core-Middleware ersetzen, schaltest du sie mit disabled ab und registrierst deine eigene unter neuem Identifier. Nur die Reihenfolge einer Core-Middleware umzubauen, kann zu Zirkelbezügen führen.
Wo du sonst an den Request kommst: Im Extbase-Controller liest du aus der Eigenschaft request die Attribute site und language. Ein eigener ViewHelper holt den Request aus dem Rendering-Kontext, über das Attribut mit dem Klassennamen ServerRequestInterface. Die globale Request-Variable ist ein Überbleibsel, und makeInstance() liefert den Request nicht, denn er ist kein Service im Container. Auf der Kommandozeile gibt es keinen Request.
Umgebung, Konfiguration und Context API
Der Application Context beschreibt die Umgebung der Installation. Es gibt drei Hauptkontexte: Production, Development und Testing. Gesetzt wird er über die Umgebungsvariable TYPO3_CONTEXT, etwa im Webserver oder in ddev. Er steht schon zu Beginn des Bootstraps fest. Fehlt die Variable, gilt Production. Testing ist für die Tests des Core reserviert. Einen Hauptkontext Staging gibt es nicht. Für einen Staging-Server nimmst du einen Unterkontext von Production:
TYPO3_CONTEXT=Production/StagingIm Code fragst du ihn mit Environment::getContext() ab. Das liefert einen ApplicationContext mit isDevelopment(), isProduction() und isTesting(). Ein Unterkontext wie Development Local zählt als Development. Direkt an Environment gibt es keine Methode isDevelopment.
Die Klasse Environment kennt außerdem die Pfade. getProjectPath() ist der Ordner mit der composer.json, dort liegt etwa ein Ordner data für Importdateien. getPublicPath() ist der Document Root, alles darin ist vom Web erreichbar. getVarPath() liegt außerhalb davon und passt für temporäre Dateien. Dazu kommen getConfigPath(), isComposerMode() und isCli(). Die Methode getComposerRootPath() ist in TYPO3 14 entfallen, die Version liefert Typo3Version.
Ein API-Schlüssel, den Administratoren unter „Extension-Konfiguration“ eintragen, gilt für die ganze Installation. Das Feld beschreibst du in ext_conf_template.txt in der Syntax von TypoScript-Konstanten:
# cat=basic; type=string; label=API-Schlüssel
apiKey =Der Wert landet in der settings.php im Konfigurationsordner. Ein Service liest ihn mit der injizierten ExtensionConfiguration und ihrer Methode get(), mit Extension-Key und Pfad. Ohne Pfad kommt das ganze Array.
Soll ein Download-Link eine Datei-ID enthalten, die niemand verändern kann, nimmst du den HashService. appendHmac() hängt eine Signatur aus dem encryptionKey und einem Geheimnis je Zweck an. validateAndStripHmac() prüft sie und wirft eine Exception, wenn der Wert verändert wurde. Die alte hmac-Methode in GeneralUtility gibt es in TYPO3 14 nicht mehr.
Die Context API ist etwas anderes. Sie sagt, für wen und wann gerade gerendert wird, und wird je Einstiegspunkt neu aufgebaut. Die Klasse Context holst du per Dependency Injection. Sie teilt ihre Informationen in Aspects:
dateliefert timestamp, iso, timezone und full. accessTime ist auf die volle Minute abgerundet und für Zugriffsprüfungen gedacht.languageliefert id, contentId und die Einstellungen für Fallback und Overlay.frontend.userundbackend.userliefern id, username, isLoggedIn, groupIds und groupNames.workspaceliefert id, isLive und isOffline. Der Live-Workspace hat immer die ID 0.visibilitysagt, ob versteckte oder gelöschte Datensätze einbezogen werden.
$now = $this->context->getPropertyFromAspect('date', 'timestamp');
$isLive = $this->context->getPropertyFromAspect('workspace', 'isLive');
$groups = $this->context->getPropertyFromAspect('frontend.user', 'groupIds');
$isMember = in_array(3, $groups, true);Bei angemeldeten Frontend-Benutzern enthält groupIds zuerst die Pseudo-Gruppen 0 und minus 2, danach die echten Gruppen. Eigenschaften wie groupId, isInGroup oder isDraft gibt es nicht. Der Standard für das Overlay ist OVERLAYS_ON_WITH_FLOATING: Übersetzungen werden überlagert, nicht übersetzte Datensätze ausgeblendet, Datensätze ohne Eltern in der Standardsprache trotzdem angezeigt.
Einen eigenen Aspect schreibst du als Klasse mit dem AspectInterface und der Methode get(). Mit setAspect() setzt du ihn unter einem Namen in den Context. Danach liest ihn jeder mit getPropertyFromAspect().
Die Site-Konfiguration
Eine Site ist ein Teilbaum mit eigener Domain, eigenen Sprachen und Routing-Regeln. Ihre Konfiguration ist eine YAML-Datei und gehört in die Versionsverwaltung. In Composer-Installationen liegt sie im Ordner config, Unterordner sites, Ordner mit dem Identifier. Bei Classic-Installationen liegt sie unter typo3conf.
# config/sites/main/config.yaml
rootPageId: 1
base: 'https://example.org/'
languages:
- languageId: 0
locale: de_DE.UTF-8
base: /de/
- languageId: 1
locale: en_US.UTF-8
base: /en/
errorHandling:
- errorCode: 404
errorHandler: Page
errorContentSource: 't3://page?uid=123'
baseVariants:
- base: 'https://example.ddev.site/'
condition: 'applicationContext == "Development"'
dependencies:
- typo3/fluid-styled-contentrootPageIdist die UID der Wurzelseite, meist mit „Ist Anfang der Website“. Alle Unterseiten gehören zur Site.baseist die Basis-URL. Daran ordnet TYPO3 Anfragen der Site zu und baut alle Links.- Unter
languageshat die Standardsprache immer die languageId 0. Weitere Sprachen bekommen eigene IDs und meist einen eigenen Pfad als base. TYPO3 wählt die Sprache nach der URL, nicht nach dem Browser. errorHandlinglegt Fehlerseiten je Statuscode fest, mit den Handlern Page, Fluid oder PHP. Der errorCode 0 gilt für alle übrigen Codes. Ein ErrorDocument in der htaccess-Datei greift nicht, denn der Webserver sieht nur eine erfolgreiche Anfrage anindex.php.baseVariantsgibt etwa dem Entwicklungssystem eine andere Basis-URL, mit Bedingungen in Symfony Expression Language. Umgebungsvariablen setzt du in base mit der env-Schreibweise in Prozentzeichen ein, in der Bedingung mit getenv.routessind statische Routen, etwa für robots.txt, mit den Typen staticText, uri oder asset.dependenciesbindet Site Sets ein.
Eigene Werte: Unbekannte Schlüssel in der YAML-Datei bleiben beim Speichern im Backend erhalten. Du liest sie mit getConfiguration() der Site. Soll ein Feld im Sites-Modul erscheinen, ergänzt du es in der Datei sites.php im Ordner Overrides unter Configuration/SiteConfiguration, in den Spalten der Site-Konfiguration. Das ist experimentell und nur für einfache Felder gedacht. Die Helfer aus ExtensionManagementUtility funktionieren dort nicht.
Site Sets, Settings und die Sites API
Ein Site Set ist ein Paket einer Extension im Ordner Configuration/Sets. Es bündelt TypoScript, Page TSconfig, Einstellungen und seit TYPO3 14.1 auch Route Enhancer. Eine Site nutzt es, indem sie seinen Namen unter dependencies einträgt. Nichts wird kopiert, und Sets können weitere Sets mitbringen.
Site Settings sind typisierte Werte je Site. Unser Set definiert sie in settings.definitions.yaml:
settings:
myext.itemsPerPage:
type: int
default: 10
label: 'Konferenzen pro Seite'Geänderte Werte aus dem Site-Settings-Editor landen in der settings.yaml der Site. Gibt es diese Datei, gelten nur ihre Werte, und settings in der config.yaml werden ignoriert. In TypoScript stehen Site Settings als Konstanten bereit:
plugin.tx_myext.settings.itemsPerPage = {$myext.itemsPerPage}Sites API: Andere Sites findest du mit dem SiteFinder. Ein Konsolenbefehl, der keinen Request hat, holt ihn per Dependency Injection und ruft getSiteByPageId() auf. Er sucht über die Rootline und wirft eine SiteNotFoundException, wenn er nichts findet.
$site = $this->siteFinder->getSiteByPageId(12);
$status = $site->getSettings()->get('redirects.httpStatusCode', 307);
$apiKey = $site->getConfiguration()['apiKey'] ?? '';Domain-Datensätze gibt es seit der Site-Konfiguration nicht mehr. In TypoScript-Bedingungen ruft die Funktion siteLanguage den passenden Getter der SiteLanguage auf, genauso arbeitet site. Bedingungen mit globalVar und dem Parameter L funktionieren nicht mehr.
[siteLanguage("languageId") == 1]
[siteLanguage("locale").getLanguageCode() == "en"]Seiten-Routing und Links
Routing ordnet eine URL einem Controller oder einer Aktion samt Parametern zu. Es arbeitet in beide Richtungen: URLs auflösen und URLs erzeugen. Sprechende URLs sind lesbarer und helfen bei Suchmaschinen.
TYPO3 nutzt dafür Symfony Routing. Dort hat eine Route einen Pfad mit Platzhaltern, defaults und requirements. Routen lassen sich per PHP-Attribut, YAML oder PHP definieren. Der UrlMatcher ordnet eine URL einer Route zu, der UrlGenerator erzeugt URLs.
Das Seiten-Routing ist immer aktiv und braucht eine Site. TYPO3 findet die Site über die Basis-URL, die Sprache über das Präfix und die Seite über ihren Slug. Das ist das Feld „URL-Segment“ mit dem ganzen Pfad der Seite. Es wird aus dem Titel vorgeschlagen. Das alte Feld alias gibt es nicht mehr, der Navigationstitel wirkt nur auf Menüs.
Ändert ein Redakteur den Slug und ist die Core-Extension redirects installiert, legt TYPO3 automatisch eine Weiterleitung von der alten auf die neue URL an. Die Site Settings autoCreateRedirects und autoUpdateSlugs sind standardmäßig an.
Links erzeugst du immer über TYPO3. In Fluid verlinken f:link.page mit pageUid und f:link.typolink mit parameter auf eine Seite, mit aktuellem Slug, Domain und Sprache. f:link.external kennt keine Seiten-UIDs. In einem Service erzeugt der Router der Site die URL:
$uri = $site->getRouter()->generateUri(12, ['_language' => 1]);Schema und Host kommen aus der base der Sprache. Links mit id und L stammen aus der Zeit vor den Sites.
Route Enhancer und Aspects
Ohne Konfiguration stehen Plugin-Argumente als Query-String in der URL, meist mit cHash. Route Enhancer unter routeEnhancers machen daraus einen lesbaren Pfad und übersetzen beim Aufruf zurück. Der Core bringt mit:
- Simple für einfache Parameter ohne Namensraum, etwa category.
- Plugin für Parameter in einem Namensraum wie tx_myext.
- Extbase zusätzlich mit Controller und Action.
- PageType als Decorator. Er hängt eine Endung wie html oder json an.
routeEnhancers:
Conferences:
type: Extbase
limitToPages: [12]
extension: MyExtension
plugin: ConferenceList
routes:
- routePath: '/seite/{page}'
_controller: 'Conference::list'
- routePath: '/{conference-title}'
_controller: 'Conference::show'
_arguments:
conference-title: conference
defaults:
page: '1'
aspects:
conference-title:
type: PersistedAliasMapper
tableName: tx_myextension_domain_model_conference
routeFieldName: path_segment
page:
type: StaticRangeMapper
start: '1'
end: '100'
PageTypeSuffix:
type: PageType
default: '.html'
map:
'.html': 0
'feed.xml': 13_controller nennt Controller und Action ohne ihre Endungen. _arguments ordnet Platzhalter den Argumenten der Action zu. Ein Platzhalter ohne Standardwert ist Pflicht, erst defaults macht ihn optional. Für Seite 1 entsteht dann die kurze URL ohne Zahl. requirements schränkt die erlaubten Werte ein.
Aspects bearbeiten je einen Platzhalter. Die Mapper: StaticValueMapper für eine feste Liste, StaticRangeMapper für Zahlenbereiche, PersistedAliasMapper für ein Datenbankfeld wie den Slug, PersistedPatternMapper für ein Muster aus mehreren Feldern. Der Modifier LocaleModifier ersetzt einen festen Pfadteil je Sprache, etwa uebersicht und overview. Seine localeMap ordnet Locale-Mustern einen Wert zu, default gilt für den Rest.
Kurz: Ein Enhancer beschreibt den zusätzlichen Pfad mit Platzhaltern. Ein Decorator hängt nur etwas an die fertige Route. Ein Mapper bildet einen einzelnen Platzhalterwert ab.
Neu in TYPO3 14: Site Sets bringen Route Enhancer in einer route-enhancers.yaml mit, die Site-Konfiguration gewinnt dabei immer. So enthält das Set typo3 seo-sitemap die Route für sitemap.xml. Und limitToPages nimmt seit 14.2 auch Ausdrücke an, alle Einträge sind mit oder verknüpft:
limitToPages:
- 'page["doktype"] == 1'Eigener Enhancer: Die Klasse erweitert AbstractEnhancer. Du registrierst sie in ext_localconf.php im Bereich routing enhancers der globalen Konfiguration unter dem Namen MyEnhancer und nutzt sie mit type MyEnhancer. Eigene Aspects kommen unter routing aspects.
Leistung und SEO: Persistierte Mapper fragen bei jedem Auflösen und Erzeugen die Datenbank ab. Mehrere URLs für denselben Inhalt erzeugen Duplicate Content, dagegen hilft ein Canonical-Tag. Parameter ohne Mapper führen zu URLs mit cHash.
Der cHash
Der Seitencache speichert Varianten einer Seite je Parameter. Mit beliebigen Zufallswerten könnte ein Angreifer den Cache fluten. Darum signiert der cHash die für den Cache relevanten Parameter mit dem geheimen encryptionKey. Nur ein gültiger cHash erzeugt eine eigene Cache-Variante.
Fehlt der cHash bei einem Plugin-Parameter oder ist er falsch, liefert TYPO3 einen 404-Fehler. Das liegt an pageNotFoundOnCHashError, das standardmäßig an ist. Erzeuge Links deshalb immer über TYPO3. Soll ein Suchbegriff nicht in die Berechnung einfließen, trägst du ihn in excludedParameters ein:
$GLOBALS['TYPO3_CONF_VARS']['FE']['cacheHash']['excludedParameters'][] = 'tx_search_pi1[query]';Mit einem Zirkumflex vorne erfasst ein Eintrag alle Parameter mit gleichem Anfang.
Lesbare URLs ohne cHash gibt es nur, wenn TYPO3 die Werte kennt oder streng prüft. Erster Weg: Aspects wie StaticValueMapper oder PersistedAliasMapper. Zweiter Weg: die Option static für einen Platzhalter mit strenger requirements-Regel. Fehlt die Regel, ignoriert TYPO3 static, und der cHash bleibt.
Sessions
Eine Session verbindet mehrere Requests eines Besuchers. Das Cookie fe_typo_user im Frontend oder be_typo_user im Backend enthält nur die Session-ID. Die Daten liegen standardmäßig in den Tabellen fe_sessions und be_sessions. Die ID steht dort nur gehasht, ein Datenbank-Leck hilft also nicht beim Übernehmen.
Der Core bringt das DatabaseSessionBackend als Standard und das RedisSessionBackend mit. Redis kennt seit TYPO3 14.2 getrennte Optionen für Benutzername und Passwort. Konfiguriert wird im Bereich SYS session der globalen Konfiguration, getrennt nach FE und BE. Eigene Backends implementieren das SessionBackendInterface.
UserSessionManager::create() mit FE erzeugt den Manager, der UserSession-Objekte lädt, prüft und speichert. Beim Abmelden beendet TYPO3 die Session und entfernt ihre Daten. Wer sich neu anmeldet, bekommt eine neue ID.
Unser Warenkorb für Gäste nutzt den Typ ses. Diese Daten gehören zur Session, auch ohne Login.
$user = $request->getAttribute('frontend.user');
$user->setKey('ses', 'myext_cart', $data);
$user->storeSessionData();Das Wichtigste in Kürze
- Frontend, Backend, Kommandozeile und Install Tool haben je eine Application, Extbase nicht.
- Middlewares stehen in
Configuration/RequestMiddlewares.phpmit target, before, after und disabled. - Requests sind unveränderlich. Das Ergebnis von withAttribute musst du zuweisen.
- Der Application Context beschreibt die Umgebung, die Context API den aktuellen Request.
- Die Site ist eine YAML-Datei mit rootPageId, base, languages, errorHandling, routes und dependencies.
- Site Settings definiert das Set, in TypoScript sind sie Konstanten.
- Enhancer machen Plugin-Argumente lesbar, Aspects übersetzen Platzhalter, PageType hängt eine Endung an.
- Ohne bekannte Werte braucht eine URL einen gültigen cHash, sonst gibt es einen 404-Fehler.
- Session-Daten brauchen
storeSessionData().
Begriffe
- Application Context
- Umgebung der Installation, gesetzt über TYPO3_CONTEXT.
- Aspect im Context
- Teil der Context API mit Informationen zum Request, etwa Datum oder Benutzer.
- Aspect im Routing
- Übersetzt einen Platzhalter einer Route, als Mapper oder Modifier.
- cHash
- Signatur der für den Cache relevanten URL-Parameter.
- Decorator
- Hängt etwas an die fertige Route, etwa eine Endung.
- Middleware
- Baustein nach PSR-15, der Request und Response bearbeitet.
- Route Enhancer
- Erweitert die Seiten-URL um lesbare Plugin-Argumente.
- Site Set
- Wiederverwendbares Konfigurationspaket einer Extension.
- Slug
- Lesbarer URL-Teil einer Seite oder eines Datensatzes.