Wie kann man TYPO3 Context nutzen, um die Umgebung zu verbessern?

Was ist TYPO3 Context?

TYPO3 Context teilt TYPO3 mit, welche Umgebung die aktuelle Anfrage bearbeitet.

• Es trennt lokale, Staging-, Test- und Produktionskonfigurationen.
• Es hilft TYPO3, die richtigen Einstellungen für jede Umgebung zu laden.
• Es verhindert, dass Entwicklungseinstellungen die Live-Website erreichen.

Was TYPO3_CONTEXT macht

TYPO3_CONTEXT ist die Umgebungsvariable, die den aktuellen TYPO3 Anwendungskontext definiert.

• Es teilt TYPO3 mit, ob das Projekt in Entwicklung, Staging, Test oder Produktion läuft.
• Es kann Datenbankeinstellungen, Site-URLs, Debugging, Cache-Verhalten, CLI-Befehle, PHP-Logik und TypoScript-Bedingungen steuern.
• Es funktioniert als Hauptumgebungsschalter für die TYPO3-Konfiguration.

Standard-TYPO3-Kontext: Produktion

Wenn kein Kontext gesetzt ist, fällt TYPO3 auf Produktion zurück.

• Dies hält Live-Websites standardmäßig sicher.
• Entwickler sollten dennoch klare Kontexte für lokale und Staging-Umgebungen definieren.
• Zum Beispiel, verwenden Sie Development/DDEV lokal und Production/Staging für Staging.

Hauptkontexte: Produktion, Entwicklung, Test

TYPO3 unterstützt drei Root-Kontexte.

• Production: für Live- oder produktionsähnliche Umgebungen.
• Development: für lokale und Entwicklungsarbeiten.
• Testing: für automatisierte Test-Workflows, nicht für normales Staging.

Beispiele für Sub-Kontexte

TYPO3 unterstützt auch Sub-Kontexte für spezifischere Setups.

• Development/Local
• Development/DDEV
• Production/Staging
• Production/Live

Wann sollten Sie den TYPO3-Anwendungskontext verwenden?

Verwenden Sie den TYPO3-Anwendungskontext, wenn ein TYPO3-Projekt in verschiedenen Umgebungen unterschiedliches Verhalten benötigt.

• Lokale Entwicklung benötigt Debugging- und Testdienste.
• Staging benötigt Vorschau-URLs und produktionsähnliches Verhalten.
• Produktion benötigt sichere Anmeldeinformationen, versteckte Fehler und optimierte Einstellungen.

Lokale Entwicklung und Debugging

Verwenden Sie den TYPO3-Kontext, um die lokale Entwicklung sicherer und einfacher zu gestalten.

• Detaillierte Fehler nur in der Entwicklung aktivieren.
• Verwenden Sie lokale Datenbank- und Mail-Testwerkzeuge.
• Halten Sie lokale Einstellungen getrennt von Staging und Produktion.

Staging- und Vorschauumgebungen

Verwenden Sie einen Staging-Kontext, bevor Änderungen die Live-Website erreichen.

• Legen Sie eine separate Staging-Basis-URL fest.
• Testen Sie produktionsähnliches Verhalten vor der Freigabe.
• Bevorzugen Sie Produktion/Staging, wenn das Staging wie die Produktion funktionieren soll.

Sicherheits- und Leistungseinstellungen für die Produktion

Verwenden Sie den TYPO3-Kontext, um Live-Websites zu schützen.

• Deaktivieren Sie sichtbare Fehler in der Produktion.
• Halten Sie Debug-Tools von öffentlichen Benutzern fern.
• Aktivieren Sie produktionsbereite Cache-, Kompressions- und Protokollierungsregeln.

Verschiedene Datenbank-, Mail-, Cache-, Protokollierungs- und Site-URL-Einstellungen

Verwenden Sie kontextbasierte Konfiguration, wenn sich Einstellungen je nach Umgebung ändern.

• Trennen Sie Datenbankanmeldeinformationen.
• Trennen Sie Mail-Transport- oder SMTP-Einstellungen.
• Trennen Sie Site-URLs, Cache-Regeln, API-Schlüssel und Protokollierungsstufen.

Wichtige Regeln, bevor TYPO3_CONTEXT gesetzt wird

Setzen Sie TYPO3_CONTEXT bevor TYPO3 startet.

• TYPO3 liest den Anwendungskontext früh im Bootstrap-Prozess.
• Erstellen Sie den Kontext nicht innerhalb von additional.php.
• Verwenden Sie gültige Root-Kontexte, bevor Sie Sub-Kontexte hinzufügen.

TYPO3 liest den Anwendungskontext vor dem Bootstrap

• TYPO3 setzt den aktuellen Anwendungskontext sehr früh im Bootstrap-Prozess.
• Das bedeutet, der Wert muss bereits verfügbar sein, bevor TYPO3 die Anfrage bearbeitet.
• Wenn er fehlt, fällt TYPO3 auf Production zurück.

TYPO3 überprüft Kontextwerte in dieser Reihenfolge

TYPO3 überprüft diese Werte, bevor der Standard verwendet wird:

1. TYPO3_CONTEXT
2. REDIRECT_TYPO3_CONTEXT
3. HTTP_TYPO3_CONTEXT
4. Production

Fügen Sie dies hinzu, da es eine häufige Frage zur Fehlerbehebung beantwortet.

Setzen Sie den Anwendungskontext nicht in additional.php

Definieren Sie TYPO3_CONTEXT nicht in config/system/additional.php.

• TYPO3 hat den Kontext bereits erkannt, bevor diese Datei verwendet wird.
• Verwenden Sie additional.php, um den Kontext zu lesen und verschiedene Einstellungen zu laden.
• Verwenden Sie es nicht, um den Kontext selbst zu erstellen.

Der Root-Kontext muss Production, Development, oder Testing sein

Der erste Teil des Kontexts muss einer der Root-Kontexte von TYPO3 sein.

• Korrekt: Development/DDEV
• Korrekt: Production/Staging
• Falsch: Staging
• Falsch: Live

Verwenden Sie nicht Testing für Staging

Verwenden Sie Testing nicht als normale Staging-Umgebung.

• Testing ist für automatisierte Test-Workflows.
• Verwenden Sie Production/Staging für produktionsähnliches Staging.
• Verwenden Sie Development/Local oder Development/DDEV für lokale Arbeiten.

Wie man den TYPO3-Kontext setzt

Setzen Sie TYPO3_CONTEXT auf Server-, Umgebungs- oder Shell-Ebene.

• Verwenden Sie Apache oder Nginx für Webanfragen.
• Verwenden Sie DDEV oder .env für lokale Entwicklung.
• Verwenden Sie Shell-Variablen für CLI-Befehle.

Setzen Sie den TYPO3-Kontext in Apache vHost oder .htaccess

Verwenden Sie Apache SetEnv für einen festen Kontext.

SetEnv TYPO3_CONTEXT Development

Verwenden Sie dies für einfache lokale, Entwicklungs- oder Einzelumgebungs-Setups.

Setzen Sie den TYPO3-Kontext mit Apache SetEnvIf nach Domain

Verwenden Sie SetEnvIf, wenn der Kontext vom Hostnamen abhängt.

SetEnvIf Host "^dev\.example\.com$" TYPO3_CONTEXT=Development
SetEnvIf Host "^staging\.example\.com$" TYPO3_CONTEXT=Production/Staging
SetEnvIf Host "^www\.example\.com$" TYPO3_CONTEXT=Production

Dies ist nützlich, wenn Entwicklung, Staging und Live unterschiedliche Domains verwenden.

Setze TYPO3-Kontext in Nginx / PHP-FPM

Übergebe den Kontext an PHP-FPM mit fastcgi_param.

location ~ \.php$ {
  include fastcgi_params;
  fastcgi_param TYPO3_CONTEXT Production/Staging;
  fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

Setze TYPO3-Kontext in DDEV

Für DDEV verwende Development/DDEV in .ddev/config.yaml.

web_environment:
- TYPO3_CONTEXT=Development/DDEV

Starte dann DDEV neu:

ddev restart

Die eigene TYPO3 CMS Einstellungsdokumentation von DDEV verwendet Development/DDEV mit web_environment, daher sollte dies das einfachere Development-Beispiel ersetzen.

TYPO3-Kontext mit Composer setzen .env

Für Composer-basierte Projekte definieren Sie den Kontext in einer Umgebungsdatei, wenn Ihre Einrichtung Umgebungsvariablen früh genug lädt.

TYPO3_CONTEXT=Development

Verwenden Sie dies nur, wenn die Umgebungsdatei geladen wird, bevor TYPO3 startet.

TYPO3-Kontext in CLI / Shell setzen

CLI-Befehle benötigen möglicherweise einen separaten Kontext.

export TYPO3_CONTEXT=Development

Oder übergeben Sie ihn direkt vor einem Befehl:

TYPO3_CONTEXT=Production/Staging vendor/bin/typo3 cache:flush

Letzte Optionen für Shared Hosting

Verwenden Sie diese nur, wenn kein Zugriff auf Serverebene verfügbar ist.

• .user.ini
• php.ini
• php.ini
• Umgebungsvariablen des Hosting-Panels

Vermeiden Sie es, den Kontext zu spät zu setzen, insbesondere in TYPO3-Laufzeitdateien.

Wie man den aktuellen TYPO3-Kontext überprüft

Nachdem Sie TYPO3_CONTEXT gesetzt haben, vergewissern Sie sich, dass TYPO3 den erwarteten Wert liest.

• Überprüfen Sie es im TYPO3-Backend.
• Überprüfen Sie es über die CLI.
• Überprüfen Sie es in PHP beim Debuggen der Konfiguration.

Überprüfen Sie es in den Systeminformationen des TYPO3-Backends

TYPO3 zeigt den aktuellen Anwendungskontext im Bereich der Systeminformationen des Backends an.

Verwenden Sie dies, um zu bestätigen, ob Webanfragen im Production, Development oder einem Unterkontext ausgeführt werden.

Überprüfen Sie es über die CLI

Verwenden Sie die Shell, um die Variable zu bestätigen.

env | grep TYPO3_CONTEXT

Für DDEV, führen Sie aus:

ddev exec env | grep TYPO3_CONTEXT

Überprüfen Sie es in PHP mit Environment::getContext()

Verwenden Sie die PHP-API von TYPO3, um den aktiven Kontext zu lesen.

$context = \TYPO3\CMS\Core\Core\Environment::getContext();

Warum CLI-Kontext und Web-Kontext unterschiedlich sein können

Webanfragen und CLI-Befehle können unterschiedliche Umgebungsvariablen verwenden.

• Der Web-Kontext stammt normalerweise von Apache, Nginx, DDEV oder Hosting-Einstellungen.
• Der CLI-Kontext stammt normalerweise von der Shell, dem Bereitstellungsskript oder dem Befehlspräfix.
• Überprüfen Sie immer beide, wenn Sie Bereitstellungsprobleme debuggen.

Wie man TYPO3-Kontext in realen Projekten verwendet

Sobald TYPO3_CONTEXT gesetzt ist, verwenden Sie es, um umgebungsspezifische Konfigurationen zu laden.

• Ändern Sie die Site-URLs je nach Kontext.
• Laden Sie separate Datenbank- oder Maileinstellungen.
• Steuern Sie PHP, TypoScript, Cache, Fehler und Logging.

Verwenden Sie TYPO3-Kontext in der Site-Konfiguration config.yaml

Verwenden Sie die Site-Konfiguration, wenn jede Umgebung eine andere Basis-URL hat.

Pfad:

config/sites//config.yaml

Verwenden Sie baseVariants für lokale, Staging- und Produktions-URLs

Verwenden Sie baseVariants, um URLs je nach Anwendungskontext zu wechseln.

base: 'https://www.example.com/'
baseVariants:
-
  base: 'https://dev.example.com/'
  condition: 'applicationContext == "Development/DDEV"'
-
  base: 'https://staging.example.com/'
  condition: ‘applicationContext == "Production/Staging"’

Verwenden Sie TYPO3-Kontext in config/system/additional.php

Verwenden Sie config/system/additional.php für kontextbasierte Systemeinstellungen.

• Aktivieren Sie nur für die Entwicklung bestimmte Einstellungen.
• Halten Sie Produktionseinstellungen sicher.
• Laden Sie umgebungsspezifische Datenbank-, Mail-, Cache- oder Logging-Konfigurationen.

Die TYPO3-Dokumentation bestätigt, dass der aktuelle Anwendungskontext in config/system/additional.php zugänglich ist.

Verwenden Sie separate Datenbankanmeldeinformationen pro Umgebung

Verwenden Sie unterschiedliche Datenbankeinstellungen für lokal, Staging und Produktion.

<?php

$context = (string)\TYPO3\CMS\Core\Core\Environment::getContext();

if ($context === 'Development/DDEV') {
  $GLOBALS['TYPO3_CONF_VARS']['DB']['Connections']['Default'] = array_replace(
      $GLOBALS['TYPO3_CONF_VARS']['DB']['Connections']['Default'] ?? [],
      [
          'dbname' => 'db',
          'host' => 'db',
          'user' => 'db',
          'password' => 'db',
          'port' => 3306,
      ]
  );
}

if ($context === 'Production') {
  $GLOBALS['TYPO3_CONF_VARS']['SYS']['displayErrors'] = 0;
}

Verwenden Sie TYPO3-Kontext in benutzerdefiniertem PHP / Erweiterungen

Verwenden Sie Environment::getContext(), wenn benutzerdefinierte Logik von der Umgebung abhängt.

$context = \TYPO3\CMS\Core\Core\Environment::getContext();

if ($context->isDevelopment()) {
  // Nur für Entwicklung bestimmte Logik
}

Verwenden Sie TYPO3-Kontext in TypoScript-Bedingungen

Verwenden Sie applicationContext in TypoScript-Bedingungen.

[applicationContext == "Production"]
config.compressJs = 1
[end]

Verwenden Sie TYPO3-Kontext für Cache, Komprimierung, Fehlerbehandlung und Protokollierung

Verwenden Sie kontextspezifische Einstellungen, um die Entwicklung flexibel und die Produktion sicher zu halten.

• Aktivieren Sie das Debugging in der Entwicklung.
• Deaktivieren Sie sichtbare Fehler in der Produktion.
• Passen Sie Cache-, Komprimierungs-, Protokollierungs- und Maileinstellungen je nach Umgebung an.

Empfohlene Strategie zur Benennung von Kontexten

Verwenden Sie klare Kontextnamen, die die Umgebung und den Zweck zeigen.

• Beginnen Sie mit einem gültigen Stammkontext.
• Fügen Sie Unterkontexte nur hinzu, wenn sie nützlich sind.
• Verwenden Sie ein einheitliches Benennungsmuster im gesamten Team.

Gute Kontextnamen

Verwenden Sie Namen wie:

• Development/Local
• Development/DDEV
• Development/Debug
• Production/Staging
• Production/Live

Zu vermeidende Kontextnamen

Vermeiden Sie Namen, die nicht mit einem gültigen Stammkontext beginnen.

• Vermeiden Sie Staging
• Vermeiden Sie Live
• Vermeiden Sie Preview
• Vermeiden Sie die Verwendung von Testing für normales Staging

Verwenden Sie Production/Staging anstelle von nur Staging.

Vorgeschlagenes Benennungsmuster für Teams

Verwenden Sie ein gemeinsames Muster in Dokumentation und Bereitstellungsskripten.

• Development/DDEV für lokale DDEV-Projekte.
• Production/Staging für Staging oder Vorschau.
• Production/Live für die Live-Website.

Sicherheits- und Bereitstellungs-Best Practices

Verwenden Sie TYPO3 Context sorgfältig in Bereitstellungs-Workflows.

• Halten Sie Produktionseinstellungen geschützt.
• Halten Sie lokale Einstellungen getrennt.
• Vermeiden Sie es, Geheimnisse in Projektdateien offenzulegen.

Produktionsanmeldedaten niemals committen

Speichern Sie keine Live-Anmeldedaten in versionskontrollierten Dateien.

• Halten Sie Produktionsdatenbank-Passwörter außerhalb von Git.
• Committen Sie keine Produktions-.env-Dateien.
• Verwenden Sie separate Anmeldedaten für lokale, Staging- und Live-Umgebungen.

Produktionsfehler deaktiviert halten

In der Produktion sollten keine detaillierten Fehler den Benutzern angezeigt werden.

• Aktivieren Sie detaillierte Fehler nur in der Entwicklung.
• Deaktivieren Sie sichtbare Fehlerausgaben auf Live-Websites.
• Halten Sie Debug-Tools von der Produktion fern.

Verwenden Sie Umgebungsvariablen für Geheimnisse, wo möglich

Verwenden Sie Umgebungsvariablen für sensible Werte.

• Datenbank-Passwörter
• SMTP-Anmeldedaten
• API-Tokens
• Externe Dienstschlüssel

Verwenden Sie TYPO3_CONTEXT, um zu entscheiden, welche Konfiguration geladen werden soll, nicht um das Geheimnis selbst zu speichern.

Halten Sie DDEV/Local-Konfigurationen aus Produktionsbereitstellungen heraus

DDEV-Einstellungen sollten lokal bleiben, es sei denn, sie werden absichtlich für die Entwicklung geteilt.

• Lokale Docker-Einstellungen nicht in die Produktion bereitstellen.
• Lokale Datenbank- und Maileinstellungen getrennt halten.
• Bereitstellungsskripte überprüfen, bevor sie live geschaltet werden.

Fehlerbehebung im TYPO3-Kontext

Wenn der TYPO3-Kontext nicht funktioniert, überprüfen Sie zuerst, wo der Wert gesetzt ist.

• Web- und CLI-Kontext können unterschiedlich sein.
• TYPO3 fällt auf Production zurück, wenn kein Kontext gefunden wird.
• Ungültige Kontextnamen können Kontextprüfungen stören.

TYPO3 zeigt immer noch Production an

TYPO3 zeigt normalerweise Production an, wenn kein gültiger Kontext erkannt wird.

• Überprüfen Sie Apache-, Nginx-, DDEV- oder Hosting-Einstellungen.
• Bestätigen Sie, dass TYPO3_CONTEXT verfügbar ist, bevor TYPO3 startet.
• Überprüfen Sie, ob REDIRECT_TYPO3_CONTEXT oder HTTP_TYPO3_CONTEXT das Verhalten überschreibt.
• TYPO3- und Server/PHP-Cache nach Änderungen leeren.

.htaccess Kontext funktioniert nicht

.htaccess-Einstellungen können fehlschlagen, wenn Apache-Overrides deaktiviert sind.

• Überprüfen Sie, ob .htaccess aktiviert ist.
• Verwenden Sie nach Möglichkeit die Apache vHost-Konfiguration.
• Bestätigen Sie, dass SetEnv, SetEnvIf oder mod_rewrite-Regeln angewendet werden.

DDEV-Kontext ändert sich nicht

DDEV benötigt normalerweise einen Neustart nach Kontextänderungen.

• Überprüfen Sie .ddev/config.yaml.
• Bestätigen Sie, dass web_environment TYPO3_CONTEXT=Development/DDEV enthält.
• Führen Sie ddev restart aus.
• Überprüfen Sie mit ddev exec env | grep TYPO3_CONTEXT.

CLI-Befehle verwenden den falschen Kontext

CLI-Befehle verwenden möglicherweise nicht denselben Kontext wie Webanfragen.

TYPO3_CONTEXT=Development/DDEV vendor/bin/typo3 cache:flush

Setzen Sie den Kontext in Ihrem Shell- oder Bereitstellungsskript, wenn nötig.

isDevelopment() oder isProduction() liefert unerwartete Ergebnisse

Dies passiert normalerweise, wenn der Root-Kontext falsch ist.

• Verwenden Sie Development/Local, nicht Local.
• Verwenden Sie Production/Staging, nicht Staging.
• Halten Sie den ersten Teil als Production, Development, oder Testing.

Backend und Frontend zeigen unterschiedliche Kontexte an

Backend und Frontend werden möglicherweise mit unterschiedlichen Server- oder PHP-Einstellungen ausgeführt.

• Überprüfen Sie die vHost-Einstellungen.
• Überprüfen Sie die PHP-FPM-Pool-Einstellungen.
• Überprüfen Sie, ob nur ein Einstiegspunkt über einen Fallback-Kontext verfügt.
• Vergleichen Sie die Backend-Anzeige, die CLI-Ausgabe und die Werte der Serverumgebung.

Optionale TYPO3-Kontext-Erweiterungen und -Tools

TYPO3-Kontext kann normalerweise mit Server-, CLI- und Projektkonfiguration gehandhabt werden.
 Erweiterungen sind optional und sollten nur verwendet werden, wenn sie komplexe Setups vereinfachen.

Wann ein konfigurationsbasierter Loader sinnvoll ist

Ein Konfigurations-Loader kann hilfreich sein, wenn ein TYPO3-Projekt viele umgebungsspezifische Dateien hat.

• Verwenden Sie ihn für komplexe Multi-Umgebungsprojekte.
• Verwenden Sie ihn, wenn Teams eine sauberere Trennung der Konfiguration benötigen.
• Vermeiden Sie ihn, wenn die Standard-TYPO3_CONTEXT-Einrichtung bereits funktioniert.

Was vor der Verwendung einer Kontext-Erweiterung zu überprüfen ist

Fügen Sie keine Kontext-Erweiterung hinzu, ohne Wartung und Kompatibilität zu überprüfen.

• Überprüfen Sie die TYPO3-Version-Unterstützung.
• Überprüfen Sie die letzten Updates.
• Lesen Sie die Dokumentation.
• Testen Sie es lokal oder in der Staging-Umgebung vor der Produktion.

Fazit

TYPO3 Context hält lokale, Staging- und Produktionseinstellungen getrennt. Es hilft TYPO3, die richtige Konfiguration für jede Umgebung zu laden.

Setzen Sie zuerst TYPO3_CONTEXT, und überprüfen Sie es dann im Backend, CLI oder PHP. Danach wenden Sie kontextbasierte Einstellungen für Site-URLs, Datenbank, TypoScript und Deployment an.