Contao-Konfigurationsdateien: config.yaml, parameters.yaml und .env erklärt

Einleitung

Wenn du mit Contao arbeitest, begegnen dir früher oder später verschiedene Dateien. Da gibt es die config.yaml, die parameters.yaml, dann noch .env und .env.local. Und irgendwie scheinen sie alle etwas mit der Konfiguration zu tun zu haben.

Aber welche Datei ist wofür zuständig? Was gehört wohin? Und warum gibt es überhaupt so viele verschiedene Dateien?

In diesem Artikel erfährst du, welchen Zweck die einzelnen Konfigurationsdateien haben und wie Contao sie verarbeitet.

Die wichtigsten Konfigurationsdateien im Überblick

Contao nimmt dir einen Grossteil der Konfiguration ab, indem es bereits sinnvolle Standardwerte mitbringt. Diese Defaults kannst du bei Bedarf überschreiben. Da Contao eine umfangreiche Anwendung ist, bietet es viele konfigurierbare Bereiche – anpassen musst du jedoch nur das, was wirklich für dein Projekt relevant ist.

config.yaml

Pfad: config/config.yaml

Im Prinzip gibt es in der Contao Managed Edition nur eine einzige Konfigurationsdatei, nämlich die config.yaml.

Du kannst jegliche Konfigurationen direkt darin vornehmen und brauchst dich in der Theorie mit den anderen Dateien überhaupt nicht beschäftigen.

Fertig, Ende des Blogbeitrags - wenn da nicht die Versionierung wäre!

Üblicherweise werden Projekte versioniert, meistens mit Git, aber für die Problematik ist es unerheblich, welche Versionsverwaltungssoftware zum Einsatz kommt.

Nachfolgend werden wir der Einfachheit halber aber Git als Beispiel nehmen.

Sobald du nämlich Datenbank-Zugangsdaten oder API-Schlüssel in deine config.yaml schreibst und diese in deinem Git-Repository speicherst ("committest"), hättest du plötzlich sensible Daten in deiner Git-Historie. Und der Sinn von Git und Co. ist es ja eben gerade, diese Information für immer zu speichern und nie zu vergessen. Das ist aus Sicherheitsgründen keine gute Idee.

Die Lösung? Genau, sensible Daten kommen in eine andere Datei und werden dann in der config.yaml via Platzhalter referenziert. Das ist im Prinzip auch schon alles, was parameters.yaml, .env und Co. tun. Auf ihre Eigenheiten kommen wir gleich nochmal zu sprechen.

In die config.yaml gehört also die Konfiguration der Contao-Applikation. Diese Datei wird nicht automatisch angelegt und du erstellst sie bei Bedarf manuell.

Contao lädt automatisch die config_prod.yaml für die Produktionsumgebung oder die config_dev.yaml für die Entwicklungsumgebung. Falls diese nicht vorhanden sind, wird die config.yaml als Fallback geladen. So kannst du generell gültige Einstellungen definieren und bei Bedarf je nach Umgebung gewisse Konfigurationsparameter anpassen.

Verwendung:

• Unterschiedliche Konfigurationen für Test- und Produktionsumgebung möglich
• Im Gegensatz zu parameters.yaml, .env und Co. wird die config.yaml in der Versionsverwaltungssoftware mit aufgenommen
• Hier konfigurierst du die Contao-Applikation
• Du legst die Datei manuell an, wenn du sie brauchst

Hilfreiche Beispiele für Einträge in der config.yaml:

1. Indexierung von geschützten Seiten aktivieren:

contao:
    search:
        index_protected: true

2. Zentrale Bildgrössen konfigurieren:

contao:
    image:
        sizes:
            header_image:
                width: 1920
                height: 600
                resizeMode: crop

3. Verschiedene weitere Contao-spezifische Einstellungen wie Crawler-Konfiguration, Upload-Limits oder Locales.

Nützliche Konsolen-Befehle:

Die Standard-Konfiguration für Contao anzeigen:

php vendor/bin/contao-console config:dump-reference contao

Die aktuelle Konfiguration anzeigen:

php vendor/bin/contao-console debug:config contao

parameters.yaml

Pfad: config/parameters.yaml

Die parameters.yaml ist historisch bedingt und stammt aus älteren Contao-Versionen. In der Contao Managed Edition wurden hier ursprünglich die Parameter für die Datenbankverbindung abgelegt. Auch das Contao Installtool hat auf diese Datei zugegriffen.

Die Datei wurde bei der Installation automatisch angelegt und sah nach der Installation so aus:

# This file has been auto-generated during installation
parameters:
    database_host: …
    database_port: …
    database_user: …
    database_password: …
    database_name: …
    secret: …

Du konntest hier auch zusätzliche Einträge ablegen, zum Beispiel die Angaben für den E-Mail-Versand über SMTP oder API-Schlüssel für Erweiterungen etc.

Die parameters.yaml ist seit Contao 4.13 als veraltet markiert. Das bedeutet, sie wird noch unterstützt (auch unter Contao 5), sollte aber nicht mehr verwendet werden. Stattdessen solltest du auf .env-Dateien umsteigen.

.env und .env.local

Pfad: /.env und /.env.local

Diese beiden Dateien liegen im Hauptverzeichnis deiner Contao-Installation, auf der gleichen Ebene wie die Ordner files und templates sowie die composer.json.

Bei der Installation von Contao per Contao Manager (ab Version 1.8) werden diese beiden Dateien automatisch erzeugt und dort die Datenbankverbindung abgelegt.

Die Env-Dateien beinhalten sogenannte Umgebungsvariablen.

Was sind Umgebungsvariablen?

Umgebungsvariablen sind Variablen, die auf Betriebssystem-Ebene, pro Benutzer oder sogar pro Prozess definiert werden können. Der grosse Vorteil: Deine Applikation ist damit für den Betrieb in Containern vorbereitet.

Es handelt sich hierbei um einen etablierten Standard, der nicht nur für Contao und Symfony gilt, sondern plattformübergreifend eingesetzt wird. Die Umgebungsvariablen lassen sich sogar zur Laufzeit ändern, was allerdings für die meisten von uns nicht relevant sein wird.

Für den Betrieb auf normalem Shared Hosting, wo du keine echten Umgebungsvariablen setzen kannst, liefert Contao die Möglichkeit mit, Umgebungsvariablen in einer .env-Datei zu definieren. Contao interpretiert diese dann, als wären es echte Umgebungsvariablen.

Unterschied zwischen .env und .env.local

Die .env-Datei:

• Wird ins Git-Repository committed und enthält KEINE echten Werte
• Dient zur Dokumentation erforderlicher Umgebungsvariablen
• Zeigt Beispielwerte und Struktur

Die .env.local-Datei:

• Wird NICHT ins Git-Repository committed (gehört in .gitignore)
• Enthält echte Werte, welche die in .env dokumentierten Werte entsprechend überschreiben
• Sensible Daten wie Passwörter und API-Keys
• Entwickler-spezifische Einstellungen

Die häufig konfigurierten Umgebungsvariablen bei Contao in der .env.local

APP_SECRET

Die Umgebungsvariable APP_SECRET wird für viele Anwendungsfälle benutzt. Von CSRF-Tokens bis URL-Signing uvm. Auch etliche Erweiterungen erfordern ein Secret für ihre Anwendungen. Dies ist eine Zeichenkette, die einmalig für deine Anwendung sein sollte. Eine Änderung dieses Wertes macht entsprechend alle signierten URIs und bspw. auch "Remember Me"-Cookies ungültig. Je nach dem was für Erweiterungen du einsetzt, solltest du prüfen, ob du diesen Wert einfach ändern darfst. Wurde er z. B. fälschlicherweise für Verschlüsselung verwendet, so wird die Entschlüsselung der Daten nicht mehr funktionieren. In diesem Fall wäre es ratsam, die Entwickler der Erweiterung zu kontaktieren und auf einen separaten Eintrag in der .env.local zu setzen (bspw. MY_EXTENSION_ENCRYPTION_KEY=...).

Empfehlungen:

• Der Wert sollte zufällig gewählte Zeichen, Zahlen und Symbole enthalten
• Empfohlene Länge: Mind. 32 Zeichen
• Ändere diesen Wert nur dann regelmässig, wenn er ausschliesslich für flüchtige Informationen verwendet wurde

DATABASE_URL

Die Informationen der Datenbankverbindung werden als Umgebungsvariable DATABASE_URL gespeichert. Sie definiert Benutzername, Passwort, Hostname, Port und Datenbanknamen.

Format:

DATABASE_URL="mysql://db_user:db_password@127.0.0.1:3306/db_name"

MAILER_DSN

Hier konfigurierst du den E-Mail-Versand.

Format:

MAILER_DSN="smtp://user:password@smtp.example.com:587"

Eigene Umgebungsvariablen definieren

Du kannst beliebige eigene Variablen definieren und dann in der config.yaml referenzieren.

Beispiel:

# .env
MYADMIN_EMAIL=admin@demo.de

# config/config.yaml
contao:
    localconfig:
        adminEmail: '%env(MYADMIN_EMAIL)%'

Welche Contao-Version nutzt welche Dateien?

Contao 4.4

• Basiert auf Symfony 3
• Verzeichnisstruktur: app/config/ statt config/
• Hauptsächlich parameters.yaml und config.yml
• .env-Dateien: Erste experimentelle Unterstützung
• Das Contao Installtool kann nur auf die parameters.yaml zugreifen

Contao 4.9

• Basiert auf Symfony 4
• .env-Dateien: Vollständige Unterstützung
• parameters.yaml: Noch unterstützt
• Datenbankverbindung kann über config/parameters.yaml ODER über .env bereitgestellt werden

Contao 4.13

• Basiert auf Symfony 5
• .env.local: Vollständig unterstützt und empfohlene Praxis
• Typischerweise musst du nur noch DATABASE_URL in .env.local anpassen
• Der Contao Manager ab Version 1.8 kann die Datenbankverbindung konfigurieren
• Der Manager versteht aber nur die .env.local, nicht die parameters.yaml

Contao 5.3

• Basiert auf Symfony 6
• Vollständig auf .env-Dateien und config.yaml migriert
• parameters.yaml: Wird noch unterstützt, sollte aber nicht mehr verwendet werden

In welcher Reihenfolge werden die Dateien geladen?

Contao basiert auf Symfony und folgt dessen Konfigurationssystem. Die Ladereihenfolge ist wichtig, denn spätere Dateien überschreiben frühere.

Umgebungsvariablen (.env-Dateien)

Die .env-Dateien werden in dieser Reihenfolge geladen:

1. System-Umgebungsvariablen (höchste Priorität, werden NIE überschrieben)
2. .env.$APP_ENV.local (z.B. .env.prod.local, .env.dev.local)
3. .env.$APP_ENV (z.B. .env.prod, .env.test)
4. .env.local (lokale Überschreibungen, nicht im Git)
5. .env (Standardwerte, im Git committed)

YAML-Konfigurationsdateien

Contao lädt automatisch config_prod.yaml oder config_dev.yaml, abhängig von der Umgebung. Falls diese nicht vorhanden sind, wird config.yaml als Fallback geladen.

Die umgebungsspezifischen Dateien überschreiben dabei die Einstellungen aus config.yaml.

Prioritäten-Hierarchie (vereinfacht)

Von höchster zu niedrigster Priorität:

1. .env.local (deine lokalen Einstellungen, überschreibt alles andere)
2. .env (Standardwerte aus dem Repository)
3. config/config_prod.yaml oder config/config_dev.yaml (umgebungsspezifisch)
4. config/config.yaml (Fallback, wenn keine umgebungsspezifische Datei vorhanden ist)
5. config/parameters.yaml (veraltet, wird durch .env-Dateien überschrieben)

.env.local oder parameters.yaml für die Datenbankverbindung?

Eine Frage, die immer wieder auftaucht: Wo soll ich die Datenbankverbindung konfigurieren?

Die Antwort: Grundsätzlich ist es Contao egal, wo die Datenbankverbindung steht.

ALLERDINGS: Der Contao Manager kann die Datenbankverbindung nur in der .env.local anpassen. Wenn die Datenbankverbindung in beiden Dateien konfiguriert ist, verwendet Contao die Daten aus der .env.local.

Empfehlung: Entscheide dich für eine Variante. Die Best Practice ist klar: Nutze .env.local.

Exkurs: Dateiendung .yaml oder .yml?

Vielleicht ist dir aufgefallen, dass manche Dateien .yaml heissen und andere .yml. Gibt es da einen Unterschied?

Die Antwort: Nein, es gibt keinen Unterschied.

Beide Dateiendungen sind gültig und werden von Contao und Symfony gleich behandelt.

Hintergrund: In älteren Betriebssystemen waren Dateierweiterungen auf drei Buchstaben beschränkt, weshalb häufig .yml verwendet wurde. Bei aktuellen Systemen spielt das keine Rolle mehr.

Empfehlung: Verwende .yaml, die vollständige Endung.

Best Practices für Contao

Damit du in Zukunft weisst, wie du mit Konfigurationsdateien umgehst, hier die wichtigsten Best Practices:

1. Ab Contao 4.13+: Verwende .env und .env.local statt parameters.yaml

2. In .env.local gehört: In 90% aller Fälle nur DATABASE_URL, APP_SECRET und MAILER_DSN hinein

3. Niemals in Git committen: .env.local, parameters.yaml, API-Keys oder sonstige Passwörter

4. Per Git Commit erlaubt: config.yaml bzw. .env (mit Platzhaltern)

5. Legacy-Projekte: Bei älteren Contao 4-Projekten kann parameters.yaml noch vorhanden sein. Bei der Migration auf neuere Versionen solltest du auf .env.local migrieren und die parameters.yaml löschen, um Verwirrungen zu vermeiden.

Fazit

Die verschiedenen Konfigurationsdateien in Contao haben klare Aufgaben. Die parameters.yaml ist historisch bedingt und sollte bei neuen Projekten nicht mehr verwendet werden. Stattdessen nutzt du die .env und .env.local für Umgebungsvariablen wie Datenbankverbindungen und Secrets.

Im Prinzip könnte alles direkt in die config.yaml geschrieben werden. Aber aus Sicherheitsgründen werden sensible Daten ausgelagert und in der config.yaml nur referenziert.

Die config.yaml ist der richtige Ort für die Bundle-Konfiguration und Anwendungseinstellungen. Sie wird ins Repository committed, während .env.local lokal bleibt und NIEMALS committed wird.

Die Ladereihenfolge ist wichtig: Spätere Dateien überschreiben frühere. .env.local hat die höchste Priorität bei den Umgebungsvariablen.

Wenn du diese Grundregeln befolgst, behältst du den Überblick über deine Contao-Konfiguration.

Hast du Fragen zu den Konfigurationsdateien? Oder gibt es ein spezielles Szenario, bei dem du unsicher bist? Schreib es in die Kommentare.