Wie man TYPO3 mit .env Dateien konfiguriert

Was ist eine .env Datei?

Heutzutage gibt es für eine Website in der Regel mehrere "Instanzen":

1. Ein (meist lokaler) Entwicklungs-Server auf dem die Entwicklung stattfindet.
2. Ein Staging-/Beta-Server auf dem Tests und Reviews durchgeführt werden.
3. Der Live-/Production-Server, der dann öffentlich zugänglich ist und die eigentliche Website darstellt.

Der "Deployment"-Zyklus sieht dann so aus: Auf dem Entwicklungs-Server findet die Entwicklung statt. Anschließend wird alles auf den Beta-Server übertragen und dort getestet und vom Kunden begutachtet. Ist alles in Ordnung wird alles auf den Live-Server übertragen und geht somit online.

Diese unterschiedlichen "Instanzen" erfordern jedoch immer auch eine unterschiedliche Konfiguration, da sie in unterschiedlichen Umgebungen laufen, wie z.B. unterschiedliche Datenbank, Domain, Mail-Konfiguration usw. Würde man nun das gesamte Projekt im Deployment-Zyklus jeweils immer von einer "Instanz" zur nächsten kopieren, müssten jedes Mal die unterschiedlichen Konfigurationen an die jeweilige Umgebung wieder angepasst werden.

Die Idee hinter der .env Datei ist nun, dass alle Konfigurationseinstellungen, die sich je nach Umgebung/"Instanz" unterscheiden, in die .env Datei ausgelagert werden. Jede "Instanz"/Umgebung erhält seine eigene .env Datei mit den zugehörigen Einstellungen, die dann im Deployment-Zyklus nicht überschrieben wird.

Durch einen dotenv-Connector wird sichergestellt, dass die Umgebungsvariablen aus der .env Datei möglichst frühzeitig in das Programm geladen und verwendet werden können.

TYPO3 mit .env Dateien konfigurieren

Im Folgenden findest Du eine Schritt-für-Schritt Anleitung, wie Du TYPO3 mit .env Dateien konfigurieren kannst.

Voraussetzung: TYPO3 muss mit Composer installiert worden sein, da sich der dotenv-connector zum "composer autoload initialisation time" einbindet, damit die Umgebungsvariablen möglichst frühzeitig zur Verfügung stehen. 

1. Installiere die Extension helhum/dotenv-connector

 composer require helhum/dotenv-connector 

2. Erstelle eine .env.example Datei mit dem folgenden Inhalt. Diese Datei dient nur als Vorlage für die weiteren .env Dateien.

TYPO3_CONTEXT=
INSTANCE=

# Site
SITE_BASE=

# System
TYPO3_TRUSTED_HOST_PATTERN=
TYPO3_DISPLAY_ERRORS=

# Database Credentials
TYPO3__DB__Connections__Default__dbname=
TYPO3__DB__Connections__Default__host=
TYPO3__DB__Connections__Default__password=
TYPO3__DB__Connections__Default__port=
TYPO3__DB__Connections__Default__user=

# Graphics
TYPO3_GFX_PROCESSOR=
TYPO3_GFX_PROCESSOR_PATH=
TYPO3_GFX_PROCESSOR_PATH_LZW=

# Mail
TYPO3_MAIL_TRANSPORT=
TYPO3_MAIL_TRANSPORT_SMTP_SERVER=
TYPO3_MAIL_TRANSPORT_SMTP_USERNAME=
TYPO3_MAIL_TRANSPORT_SMTP_PASSWORD=
TYPO3_MAIL_DEFAULTMAILFROMADDRESS=

3. Erstelle eine Kopie der .env.example Datei und benenne sie in .env um. Die .env Datei muss im root-Verzeichnis gespeichert werden, in dem sich auch die composer.json Datei befindet!

4. Öffne die .env Datei im Editor Deiner Wahl und fülle die Daten für Deine lokale Entwicklungsumgebung aus. Für eine DDEV-Installation von TYPO3 könnte die .env Datei z.B. so aussehen:

TYPO3_CONTEXT='Development'
INSTANCE='local'

# Site
SITE_BASE='https://myproject.ddev.site/'

# System
TYPO3_TRUSTED_HOST_PATTERN='.*.*'
TYPO3_DISPLAY_ERRORS='1'

# Database Credentials
TYPO3__DB__Connections__Default__dbname='db'
TYPO3__DB__Connections__Default__host='ddev-myproject-db'
TYPO3__DB__Connections__Default__password='db'
TYPO3__DB__Connections__Default__port='3306'
TYPO3__DB__Connections__Default__user='db'

# Graphics
TYPO3_GFX_PROCESSOR='ImageMagick'
TYPO3_GFX_PROCESSOR_PATH='/usr/bin/'
TYPO3_GFX_PROCESSOR_PATH_LZW='/usr/bin/'

# Mail
TYPO3_MAIL_TRANSPORT='smtp'
TYPO3_MAIL_TRANSPORT_SMTP_SERVER='localhost:1025'
TYPO3_MAIL_TRANSPORT_SMTP_USERNAME=''
TYPO3_MAIL_TRANSPORT_SMTP_PASSWORD=''
TYPO3_MAIL_DEFAULTMAILFROMADDRESS='no-reply@myproject.ddev.site'

5. Öffne die Datei public/typo3conf/AdditionalConfiguration.php im Editor Deiner Wahl und ersetze alle Variablenwerte durch getenv('.env-Variable'). Das Ergebnis sollte in etwa wie folgt aussehen:

<?php

$GLOBALS['TYPO3_CONF_VARS'] = array_replace_recursive(
    $GLOBALS['TYPO3_CONF_VARS'],
    [
        'DB' => [
            'Connections' => [
                'Default' => [
                    'dbname' => getenv('TYPO3__DB__Connections__Default__dbname'),
                    'host' => getenv('TYPO3__DB__Connections__Default__host'),
                    'password' => getenv('TYPO3__DB__Connections__Default__password'),
                    'port' => getenv('TYPO3__DB__Connections__Default__port'),
                    'user' => getenv('TYPO3__DB__Connections__Default__user'),
                    'driver' => 'mysqli',
                ],
            ],
        ],
        'GFX' => [
            'processor' => getenv('TYPO3_GFX_PROCESSOR'),
            'processor_path' => getenv('TYPO3_GFX_PROCESSOR_PATH'),
            'processor_path_lzw' => getenv('TYPO3_GFX_PROCESSOR_PATH_LZW'),
        ],
        'MAIL' => [
            'transport' => getenv('TYPO3_MAIL_TRANSPORT'),
            'transport_smtp_server' => getenv('TYPO3_MAIL_TRANSPORT_SMTP_SERVER'),
            'transport_smtp_username' => getenv('TYPO3_MAIL_TRANSPORT_SMTP_USERNAME'),
            'transport_smtp_password' => getenv('TYPO3_MAIL_TRANSPORT_SMTP_PASSWORD'),
            'defaultMailFromAddress' => getenv('TYPO3_MAIL_DEFAULTMAILFROMADDRESS'),
        ],
        'SYS' => [
            'trustedHostsPattern' => getenv('TYPO3_TRUSTED_HOST_PATTERN'),
            'devIPmask' => '*',
            'displayErrors' => getenv('TYPO3_DISPLAY_ERRORS'),
        ],
    ]
);

6. Öffne die Datei config/sites/main/config.yaml (/main/ könnte eventuell auch anders heissen, falls Du bei der Erstellung der Site-Configuration einen anderen Namen für den "Site Identifier" angegeben hast).
Ändere den Wert für "base" wie folgt:

base: '%env(SITE_BASE)%'

7. Starte TYPO3 neu und teste ob alles funktioniert.

8. Erstelle jeweils eine weitere .env Datei nach dem obigen Muster für den Staging-/Beta-Server und den Live-/Production-Server und passe die zugehörigen Werte in der .env Datei an die jeweilige Umgebung an. Anschließend speicher die zugehörige .env Datei auf dem entsprechenden Server jeweils im root-Verzeichnis, wo auch die composer.json zu finden ist.

Wenn Du ein Deployment-System verwendest, stelle sicher, dass die .env Datei nicht überschrieben wird. Verwendest Du z.B. Deployer solltest Du die .env Datei im Ordner /shared/ speichern und in der deployer.php Datei als "shared" definieren:

set('shared_files', ['.env']);

9. Teste ob auch TYPO3 auf dem Beta- und Live-Server fehlerfrei läuft.

10. Stelle sicher, dass die .env Dateien für den Beta- und Live-Server nicht auf GitHub gespeichert werden! Die .env.example Datei und die .env Datei für den lokalen Entwicklungsserver kannst Du jedoch auch zum Git Repository hinzufügen.

Mehr zum Thema .env findest Du hier.