Konfiguration

Einführung

Alle Konfigurationsdateien des Laravel-Frameworks liegen im Verzeichnis config/. Zu jeder Option gibt es einen Kommentar; öffnen Sie die Dateien und werfen Sie einen Blick auf die verfügbaren Optionen. In den Konfigurationsdateien werden Datenbank-Zugangsdaten, Mailserver-Einstellungen, die Anwendungs-URL, der Verschlüsselungsschlüssel und viele weitere Kernwerte verwaltet.

Der Befehl `about`

Mit dem Artisan-Befehl about erhalten Sie eine Übersicht über Konfiguration, Treiber und Umgebung Ihrer Anwendung.

php artisan about

Möchten Sie nur einen bestimmten Abschnitt sehen, nutzen Sie --only.

php artisan about --only=environment

Um die Werte einer bestimmten Konfigurationsdatei im Detail anzusehen, ist config:show praktisch.

php artisan config:show database

Umgebungskonfiguration (.env)

Häufig möchten Sie Konfigurationswerte je nach Ausführungsumgebung umschalten – zum Beispiel unterschiedliche Cache-Treiber lokal und in Produktion. Laravel nutzt dafür die PHP-Bibliothek DotEnv. Bei einer Neuinstallation enthält das Projekt-Root eine Datei .env.example mit üblichen Umgebungsvariablen, die während der Installation automatisch nach .env kopiert wird.

Bei Teamentwicklung ist es hilfreich, .env.example gepflegt in der Repository-Historie zu halten. Mit Platzhalterwerten sehen andere Teammitglieder klar, welche Umgebungsvariablen benötigt werden.

Sicherheit der Umgebungsdateien

Committen Sie die .env-Datei nicht in die Versionskontrolle. Jeder Entwickler und Server benötigt eigene Werte; im Repository besteht bei einem Zwischenfall das Risiko, dass sensible Informationen preisgegeben werden.

Laravel bringt jedoch eine Verschlüsselungsfunktion mit, sodass Sie verschlüsselte Umgebungsdateien sicher in der Versionskontrolle ablegen können.

Zusätzliche Umgebungsdateien

Beim Start der Anwendung prüft Laravel, ob die Umgebungsvariable APP_ENV oder das CLI-Argument --env gesetzt ist. Ist dies der Fall und existiert eine Datei .env.[APP_ENV], wird diese geladen. Andernfalls wird die Standard-.env verwendet.

Typen von Umgebungsvariablen

Alle Werte in der .env-Datei werden als Strings geparst. Damit env() aber unterschiedliche Typen zurückgeben kann, sind einige Spezialwerte vordefiniert.

Wert in `.env`	Rückgabewert von `env()`
`true`	`(bool) true`
`(true)`	`(bool) true`
`false`	`(bool) false`
`(false)`	`(bool) false`
`empty`	`(string) ''`
`(empty)`	`(string) ''`
`null`	`(null) null`
`(null)`	`(null) null`

Werte mit Leerzeichen setzen Sie in doppelte Anführungszeichen.

APP_NAME="My Application"

Umgebungsvariablen abrufen

Alle Variablen aus .env werden bei jedem Request in das PHP-Superglobal $_ENV geladen. Innerhalb von Konfigurationsdateien holen Sie Werte über die Funktion env().

'debug' => (bool) env('APP_DEBUG', false),

Das zweite Argument ist der Standardwert, der zurückgegeben wird, wenn die Variable nicht existiert.

Aktuelle Umgebung ermitteln

Die aktuelle Umgebung wird durch die Variable APP_ENV in der .env-Datei bestimmt. Sie lässt sich mit der Methode environment der Facade App abrufen.

use Illuminate\Support\Facades\App;

$environment = App::environment();

Mit Argumenten prüfen Sie eine bestimmte Umgebung.

if (App::environment('local')) {
    // lokale Umgebung
}

if (App::environment(['local', 'staging'])) {
    // lokal oder Staging
}

Umgebungsdateien verschlüsseln

Unverschlüsselte Umgebungsdateien gehören nicht in die Versionskontrolle. Laravel bietet jedoch eine Funktion zum Verschlüsseln von Umgebungsdateien.

Verschlüsselung

Zum Verschlüsseln einer Umgebungsdatei verwenden Sie den Befehl env:encrypt.

php artisan env:encrypt

Beim Ausführen wird die .env-Datei verschlüsselt und der verschlüsselte Inhalt in einer Datei .env.encrypted gespeichert. Der Entschlüsselungsschlüssel wird in der Ausgabe des Befehls angezeigt – bewahren Sie ihn in einem sicheren Passwortmanager auf. Möchten Sie einen eigenen Verschlüsselungsschlüssel angeben, nutzen Sie die Option --key.

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

Die Länge des angegebenen Schlüssels muss mit der vom verwendeten Verschlüsselungsverfahren geforderten Schlüssellänge übereinstimmen. Standardmäßig wird AES-256-CBC verwendet, das einen 32 Zeichen langen Schlüssel benötigt. Über die Option --cipher können Sie jedes von Laravels Verschlüsselung unterstützte Verfahren einsetzen.

Verfügt Ihre Anwendung über mehrere Umgebungsdateien wie .env und .env.staging, geben Sie mit der Option --env an, welche Umgebung verschlüsselt werden soll.

php artisan env:encrypt --env=staging

Lesbare Variablennamen

Beim Verschlüsseln einer Umgebungsdatei können Sie mit der Option --readable nur die Werte verschlüsseln und die Variablennamen lesbar belassen.

php artisan env:encrypt --readable

Dadurch entsteht eine verschlüsselte Datei im folgenden Format:

APP_NAME=eyJpdiI6...
APP_ENV=eyJpdiI6...
APP_KEY=eyJpdiI6...
APP_DEBUG=eyJpdiI6...
APP_URL=eyJpdiI6...

Mit dem lesbaren Format sehen Sie, welche Umgebungsvariablen vorhanden sind, ohne sensible Daten offenzulegen. Auch das Review von Pull Requests wird einfacher, da Sie erkennen, welche Variablen hinzugefügt, entfernt oder geändert wurden, ohne die Datei entschlüsseln zu müssen. Beim Entschlüsseln erkennt Laravel automatisch, welches Format verwendet wurde, sodass für den Befehl env:decrypt keine zusätzlichen Optionen erforderlich sind.

Bei Verwendung der Option --readable werden Kommentare und Leerzeilen aus der ursprünglichen Umgebungsdatei nicht in die verschlüsselte Ausgabe übernommen.

Lesbare verschlüsselte Umgebungsdateien aktualisieren

Beim Aktualisieren einer lesbaren verschlüsselten Umgebungsdatei behält Laravel unveränderte Werte bei und entfernt Variablen, die in der Quell-Umgebungsdatei nicht mehr existieren.

php artisan env:encrypt --readable --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

Existiert die verschlüsselte Datei noch nicht, wird sie neu erstellt. Beim Aktualisieren einer bestehenden Datei geben Sie denselben Verschlüsselungsschlüssel und dasselbe Verfahren an, mit denen die Datei erstellt wurde. Kann die Datei nicht entschlüsselt werden, schlägt der Befehl fehl, ohne die vorhandene Datei zu überschreiben. Möchten Sie alle Werte zwangsweise neu verschlüsseln, verwenden Sie die Option --force. Damit können Sie den Verschlüsselungsschlüssel wechseln oder eine ungültige verschlüsselte Datei ersetzen.

php artisan env:encrypt --readable --force --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

Entschlüsselung

Zum Entschlüsseln einer Umgebungsdatei verwenden Sie den Befehl env:decrypt. Dieser benötigt einen Entschlüsselungsschlüssel, den Laravel aus der Umgebungsvariable LARAVEL_ENV_ENCRYPTION_KEY bezieht.

php artisan env:decrypt

Alternativ können Sie den Schlüssel direkt über die Option --key übergeben.

php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

Wird der Befehl env:decrypt ausgeführt, entschlüsselt Laravel den Inhalt der Datei .env.encrypted und schreibt ihn in die Datei .env. Für ein benutzerdefiniertes Verschlüsselungsverfahren geben Sie die Option --cipher an.

php artisan env:decrypt --key=qUWuNRdfuImXcKxZ --cipher=AES-128-CBC

Verfügt Ihre Anwendung über mehrere Umgebungsdateien wie .env und .env.staging, geben Sie mit der Option --env an, welche Umgebung entschlüsselt werden soll.

php artisan env:decrypt --env=staging

Um eine bestehende Umgebungsdatei zu überschreiben, geben Sie die Option --force an.

php artisan env:decrypt --force

Zugriff auf Konfigurationswerte

Mit der Facade Config oder der globalen Funktion config() greifen Sie überall in Ihrer Anwendung auf Konfigurationswerte zu. Sie verwenden die „Punkt”-Notation aus Dateiname und Optionsname.

use Illuminate\Support\Facades\Config;

$value = Config::get('app.timezone');

// Auch über die globale Funktion
$value = config('app.timezone');

// Default-Wert angeben, falls Schlüssel fehlt
$value = config('app.timezone', 'Asia/Tokyo');

Zur Laufzeit setzen Sie Werte über Config::set() oder indem Sie ein Array an config() übergeben.

Config::set('app.timezone', 'America/Chicago');

config(['app.timezone' => 'America/Chicago']);

Es gibt auch typisierte Getter, die eine Ausnahme werfen, wenn der Typ nicht passt.

Config::string('config-key');
Config::integer('config-key');
Config::float('config-key');
Config::boolean('config-key');
Config::array('config-key');
Config::collection('config-key');

Konfigurations-Cache

Für bessere Performance können Sie alle Konfigurationsdateien in einer Datei zwischenspeichern.

php artisan config:cache

Der Befehl kombiniert alle Konfigurationsoptionen in einer Datei, die das Framework besonders schnell laden kann.

Führen Sie config:cache als Teil Ihres Produktions-Deployments aus. Während der lokalen Entwicklung ändern sich Konfigurationen häufig – dort sollten Sie ihn nicht ausführen.

Sobald der Cache existiert, wird die .env-Datei bei Anfragen oder Artisan-Aufrufen nicht mehr geladen. env() liefert dann nur noch systemseitige Umgebungsvariablen.

Rufen Sie env() daher ausschließlich aus Dateien im Verzeichnis config/ auf. Im Rest Ihrer Anwendung greifen Sie über config() auf Werte zu.

Den Cache leeren Sie mit config:clear.

php artisan config:clear

Konfigurationsdateien veröffentlichen

Viele Konfigurationsdateien liegen bereits im Verzeichnis config/, aber einige wie cors.php oder view.php sind standardmäßig nicht sichtbar. Zum Veröffentlichen verwenden Sie config:publish.

php artisan config:publish

php artisan config:publish --all

Debug-Modus

Die Option debug in config/app.php legt fest, wie viele Fehlerinformationen Nutzern angezeigt werden. Sie folgt standardmäßig dem Wert von APP_DEBUG in .env.

Setzen Sie APP_DEBUG in Produktion immer auf false. Bleibt der Wert auf true, könnten sensible Konfigurationsdaten an Endnutzer gelangen.

# Lokale Entwicklung
APP_DEBUG=true

# Produktion
APP_DEBUG=false

Wartungsmodus

Im Wartungsmodus wird für jede Anfrage eine benutzerdefinierte View angezeigt. So können Sie die Anwendung während Updates oder Wartungsarbeiten vorübergehend „deaktivieren”.

Wartungsmodus aktivieren

php artisan down

Mit der Option --refresh wird der Browser nach der angegebenen Zeit automatisch neu geladen.

php artisan down --refresh=15

Die Option --retry wird als Wert für den HTTP-Header Retry-After verwendet.

php artisan down --retry=60

Wartungsmodus umgehen

Über ein Secret-Token gewähren Sie einzelnen Nutzern Zugang.

php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515"

Mit --with-secret erzeugt Laravel das Token automatisch.

php artisan down --with-secret

Wartungsmodus in Multi-Server-Setups

Standardmäßig verwaltet Laravel den Wartungsmodus dateibasiert. Bei mehreren Servern ist die cachebasierte Variante praktisch.

APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database

Wartungs-View vorab rendern

Wenn Sie während eines Deployments php artisan down ausführen, könnten Nutzer während des Update-Prozesses Fehler zu Gesicht bekommen. Mit --render können Sie die View vorab rendern.

php artisan down --render="errors::503"

Alternativ leiten Sie im Wartungsmodus alle Anfragen an eine URL um.

php artisan down --redirect=/

Wartungsmodus deaktivieren

php artisan up

Sie können das Standard-Wartungs-Template anpassen, indem Sie resources/views/errors/503.blade.php anlegen.

Wenn Sie Downtime vollständig vermeiden möchten, ziehen Sie eine vollständig verwaltete Plattform wie Laravel Cloud in Betracht.

Nächste Schritte

Routing

Lernen Sie die Grundlagen des Routings zur Verknüpfung von URLs und Controllern.

Erste Schritte

Grundlagen

Request-Verarbeitung

Datenbank

Authentifizierung

Helfer und externe Kommunikation

Tests und Deployment

KI-Entwicklungsunterstützung

Einführung

Der Befehl `about`

Umgebungskonfiguration (.env)

Sicherheit der Umgebungsdateien

Zusätzliche Umgebungsdateien

Typen von Umgebungsvariablen

Umgebungsvariablen abrufen

Aktuelle Umgebung ermitteln

Umgebungsdateien verschlüsseln

Verschlüsselung

Lesbare Variablennamen

Lesbare verschlüsselte Umgebungsdateien aktualisieren

Entschlüsselung

Zugriff auf Konfigurationswerte

Konfigurations-Cache

Konfigurationsdateien veröffentlichen

Debug-Modus

Wartungsmodus

Wartungsmodus aktivieren

Wartungsmodus umgehen

Wartungsmodus in Multi-Server-Setups

Wartungs-View vorab rendern

Wartungsmodus deaktivieren

Nächste Schritte

Routing

​Einführung

​Der Befehl about

​Umgebungskonfiguration (.env)

​Sicherheit der Umgebungsdateien

​Zusätzliche Umgebungsdateien

​Typen von Umgebungsvariablen

​Umgebungsvariablen abrufen

​Aktuelle Umgebung ermitteln

​Umgebungsdateien verschlüsseln

​Verschlüsselung

​Lesbare Variablennamen

​Lesbare verschlüsselte Umgebungsdateien aktualisieren

​Entschlüsselung

​Zugriff auf Konfigurationswerte

​Konfigurations-Cache

​Konfigurationsdateien veröffentlichen

​Debug-Modus

​Wartungsmodus

​Wartungsmodus aktivieren

​Wartungsmodus umgehen

​Wartungsmodus in Multi-Server-Setups

​Wartungs-View vorab rendern

​Wartungsmodus deaktivieren

​Nächste Schritte

Routing

Einführung

Der Befehl `about`

Umgebungskonfiguration (.env)

Sicherheit der Umgebungsdateien

Zusätzliche Umgebungsdateien

Typen von Umgebungsvariablen

Umgebungsvariablen abrufen

Aktuelle Umgebung ermitteln

Umgebungsdateien verschlüsseln

Verschlüsselung

Lesbare Variablennamen

Lesbare verschlüsselte Umgebungsdateien aktualisieren

Entschlüsselung

Zugriff auf Konfigurationswerte

Konfigurations-Cache

Konfigurationsdateien veröffentlichen

Debug-Modus

Wartungsmodus

Wartungsmodus aktivieren

Wartungsmodus umgehen

Wartungsmodus in Multi-Server-Setups

Wartungs-View vorab rendern

Wartungsmodus deaktivieren

Nächste Schritte