Lädt automatisch Umgebungsvariablen von .env nach getenv(), $_ENV und $_SERVER.
Warum .env?
Sie sollten niemals sensible Daten in Ihrem Code speichern. Die Speicherung von Konfigurationen in der Umgebung ist einer der Grundsätze einer Zwölf-Faktoren-App. Alles, was sich zwischen verschiedenen Bereitstellungsumgebungen ändern kann – wie z. B. Datenbankdaten oder Zugangsdaten für Dienste von Drittanbietern – sollte aus dem Code in Umgebungsvariablen extrahiert werden.
Grundsätzlich ist eine .env-Datei eine einfache Möglichkeit, benutzerdefinierte Konfigurationsvariablen zu laden, die Ihre Anwendung benötigt, ohne dass Sie .htaccess-Dateien oder virtuelle Apache/nginx-Hosts ändern müssen. Das bedeutet, dass Sie keine Dateien außerhalb des Projekts bearbeiten müssen und dass alle Umgebungsvariablen immer gesetzt sind, egal wie Sie Ihr Projekt ausführen – Apache, Nginx, CLI und sogar der in PHP integrierte Webserver. Es ist VIEL einfacher als alle anderen Möglichkeiten, die Sie kennen, um Umgebungsvariablen zu setzen, und Sie werden es lieben!
- Kein Editieren von virtuellen Hosts in Apache oder Nginx
- Kein Hinzufügen von
php_valueFlags zu .htaccess-Dateien - Einfache Portabilität und gemeinsame Nutzung der erforderlichen ENV-Werte
- KOMPATIBEL mit dem in PHP eingebauten Webserver und CLI-Runner
PHP dotenv ist eine PHP-Version des ursprünglichen Rubydotenv.
Installation
Die Installation ist supereinfach über Composer:
$ composer require vlucas/phpdotenv
oder fügen Sie es von Hand zu Ihrer composer.json Datei hinzu.
Upgrading
Wir folgen der semantischen Versionierung, was bedeutet, dass zwischen den Hauptversionen Änderungen auftreten können. Wir haben Upgrade-Anleitungen für V2 zu V3, V3 zu V4 und V4 zu V5 hier verfügbar.
Verwendung
Die .env Datei wird im Allgemeinen aus der Versionskontrolle herausgehalten, da sie sensible API-Schlüssel und Passwörter enthalten kann. Es wird eine separate .env.example-Datei erstellt, in der alle erforderlichen Umgebungsvariablen definiert sind, mit Ausnahme der sensiblen Variablen, die entweder von den Benutzern für ihre eigenen Entwicklungsumgebungen bereitgestellt werden oder den Projektmitarbeitern anderweitig mitgeteilt werden. Die Projektmitarbeiter kopieren dann unabhängig voneinander die .env.example-Datei in eine lokale .env-Datei und stellen sicher, dass alle Einstellungen für ihre lokale Umgebung korrekt sind, indem sie die geheimen Schlüssel ausfüllen oder bei Bedarf ihre eigenen Werte eingeben. Bei dieser Verwendung sollte die .envDatei zur .gitignore-Datei des Projekts hinzugefügt werden, damit sie niemals von den Mitarbeitern übertragen wird. Diese Verwendung stellt sicher, dass keine sensiblen Passwörter oder API-Schlüssel jemals in der Versionskontrollhistorie zu finden sind, so dass das Risiko eines Sicherheitsverstoßes geringer ist und die Produktionswerte niemals an alle Projektmitarbeiter weitergegeben werden müssen.
Fügen Sie Ihre Anwendungskonfiguration zu einer .env-Datei im Stammverzeichnis Ihres Projekts hinzu. Stellen Sie sicher, dass die .env-Datei zu Ihrem .gitignore hinzugefügt wird, damit sie im Code nicht überprüft wird
S3_BUCKET="dotenv"SECRET_KEY="souper_seekret_key"
Erstellen Sie nun eine Datei namens .env.example und checken Sie diese in das Projekt ein. Diese sollte die ENV-Variablen enthalten, die Sie setzen müssen, aber die Werte sollten entweder leer sein oder mit Dummy-Daten gefüllt werden. Die Idee ist, die Leute wissen zu lassen, welche Variablen benötigt werden, aber ihnen nicht die sensiblen Produktionswerte zu geben.
S3_BUCKET="devbucket"SECRET_KEY="abc123"
Sie können dann .env in Ihre Anwendung laden mit:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);$dotenv->load();
Um die Ausnahme zu unterdrücken, die geworfen wird, wenn keine .env-Datei vorhanden ist, können Sie:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);$dotenv->safeLoad();
Optional können Sie einen Dateinamen als zweiten Parameter übergeben, wenn Sie etwas anderes als .env verwenden möchten:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__, 'myconfig');$dotenv->load();
Alle definierten Variablen sind jetzt in den $_ENV und $_SERVERSuper-Globalen verfügbar.
$s3_bucket = $_ENV;$s3_bucket = $_SERVER;
Putenv und Getenv
Von der Verwendung von getenv() und putenv() wird dringend abgeraten, da diese Funktionen nicht thread-sicher sind, aber es ist trotzdem möglich,PHP dotenv anzuweisen, diese Funktionen zu verwenden. Anstatt Dotenv::createImmutable aufzurufen, kann man Dotenv::createUnsafeImmutable aufrufen, das PutenvAdapter hinter den Kulissen hinzufügt. Ihre Umgebungsvariablen sind nun mit der getenv-Methode verfügbar, ebenso wie die Superglobalen:
$s3_bucket = getenv('S3_BUCKET');$s3_bucket = $_ENV;$s3_bucket = $_SERVER;
Verschachtelte Variablen
Es ist möglich, eine Umgebungsvariable in einer anderen zu verschachteln, was nützlich ist, um Wiederholungen zu vermeiden.
Das geschieht, indem man eine bestehende Umgebungsvariable in ${…} einwickelt, z.B.
BASE_DIR="/var/webroot/project-root"CACHE_DIR="${BASE_DIR}/cache"TMP_DIR="${BASE_DIR}/tmp"
Unveränderlichkeit und Repository-Anpassung
Die Unveränderlichkeit bezieht sich darauf, ob Dotenv bestehende Umgebungsvariablen überschreiben darf. Wenn Sie möchten, dass Dotenv bestehende Umgebungsvariablen überschreibt, verwenden Sie createMutable anstelle von createImmutable:
$dotenv = Dotenv\Dotenv::createMutable(__DIR__);$dotenv->load();
Hinter den Kulissen wird das „Repository“ angewiesen, Unveränderbarkeit zuzulassen oder nicht. Standardmäßig ist das Repository so konfiguriert, dass es das Überschreiben vorhandener Werte erlaubt, was relevant ist, wenn man die „create“-Methode aufruft, die RepositoryBuilder verwendet, um ein benutzerdefiniertes Repository zu erstellen:
$repository = Dotenv\Repository\RepositoryBuilder::createWithNoAdapters() ->addAdapter(Dotenv\Repository\Adapter\EnvConstAdapter::class) ->addWriter(Dotenv\Repository\Adapter\PutenvAdapter::class) ->immutable() ->make();$dotenv = Dotenv\Dotenv::create($repository, __DIR__);$dotenv->load();
Das obige Beispiel schreibt geladene Werte in $_ENV und putenv, aber bei der Interpolation von Umgebungsvariablen lesen wir nur aus $_ENV. Außerdem werden keine Variablen ersetzt, die bereits vor dem Laden der Datei gesetzt wurden.
Anhand eines anderen Beispiels kann man auch einen Satz von Variablen angeben, die nicht aufgelistet werden dürfen. Das bedeutet, dass nur die Variablen in der Zulassen-Liste geladen werden:
$repository = Dotenv\Repository\RepositoryBuilder::createWithDefaultAdapters() ->allowList() ->make();$dotenv = Dotenv\Dotenv::create($repository, __DIR__);$dotenv->load();
Variablen müssen gesetzt werden
PHP dotenv hat eine eingebaute Validierungsfunktionalität, die auch das Vorhandensein einer Umgebungsvariablen erzwingt. Dies ist besonders nützlich, um Leute über explizit benötigte Variablen zu informieren, ohne die Ihre Anwendung nicht funktionieren wird.
Sie können eine einzelne Zeichenkette verwenden:
$dotenv->required('DATABASE_DSN');
oder ein Array von Zeichenketten:
$dotenv->required();
Wenn irgendwelche ENV-Variablen fehlen, wird Dotenv eine RuntimeException wie diese ausgeben:
One or more environment variables failed assertions: DATABASE_DSN is missingLeere Variablen
Nicht nur, dass eine Variable gesetzt sein muss, man muss auch sicherstellen, dass die Variable nicht leer ist:
$dotenv->required('DATABASE_DSN')->notEmpty();
Wenn die Umgebungsvariable leer ist, erhalten Sie eine Exception:
One or more environment variables failed assertions: DATABASE_DSN is emptyGanzzahlige Variablen
Sie müssen möglicherweise auch sicherstellen, dass die Variable einen ganzzahligen Wert hat. Sie können Folgendes tun:
$dotenv->required('FOO')->isInteger();
Wenn die Umgebungsvariable keine ganze Zahl ist, erhalten Sie eine Exception:
One or more environment variables failed assertions: FOO is not an integer.Es kann sein, dass Sie die Validierungsregeln nur durchsetzen wollen, wenn eine Variable gesetzt ist. Auch dies wird von Wes unterstützt:
$dotenv->ifPresent('FOO')->isInteger();
Boolesche Variablen
Es kann sein, dass Sie sicherstellen müssen, dass eine Variable in Form eines Booleschen Wertes vorliegt, der „true“, „false“, „On“, „1“, „Yes“, „Off“, „0“ und „No“ akzeptiert. Sie können wie folgt vorgehen:
$dotenv->required('FOO')->isBoolean();
Wenn die Umgebungsvariable kein Boolescher Wert ist, erhalten Sie eine Ausnahme:
One or more environment variables failed assertions: FOO is not a boolean.Ähnlich kann man schreiben:
$dotenv->ifPresent('FOO')->isBoolean();
Erlaubte Werte
Es ist auch möglich, eine Reihe von Werten zu definieren, die Ihre Umgebungsvariablen haben sollen. Dies ist besonders nützlich in Situationen, in denen nur eine Handvoll von Optionen oder Treibern tatsächlich von Ihrem Code unterstützt werden:
$dotenv->required('SESSION_STORE')->allowedValues();
Wenn die Umgebungsvariable nicht in dieser Liste der erlaubten Werte enthalten wäre, würden Sie eine ähnliche Ausnahme erhalten:
One or more environment variables failed assertions: SESSION_STORE is not an allowed value.Es ist auch möglich, eine Regex zu definieren, die Ihre Umgebungsvariable sein sollte.
$dotenv->required('FOO')->allowedRegexValues('(]{3})');
Sie können Ihre .env-Datei mit dem Zeichen # kommentieren. Z.B.
# this is a commentVAR="value" # commentVAR=value # comment
Parsing ohne Laden
Manchmal möchte man einfach die Datei parsen und die verschachtelten Umgebungsvariablen auflösen, indem man uns einen String gibt und ein Array zurückbekommt. Das ist zwar bereits möglich, aber etwas umständlich, deshalb haben wir einen direkten Weg dafür vorgesehen:
// Dotenv\Dotenv::parse("FOO=Bar\nBAZ=\"Hello ${FOO}\"");
Das ist genau dasselbe wie:
Dotenv\Dotenv::createArrayBacked(__DIR__)->load();
nur, dass Sie statt des Verzeichnisses, in dem die Datei zu finden ist, direkt den Inhalt der Datei angegeben haben.
Hinweise zur Verwendung
Wenn ein neuer Entwickler Ihre Codebasis klont, muss er die Datei .env.example manuell nach .env kopieren und seine eigenen Werte eintragen (oder sensible Werte von einem Projektmitarbeiter erhalten).
Sicherheit
Wenn Sie eine Sicherheitslücke in diesem Paket entdecken, senden Sie bitte eine E-Mail an Graham Campbell unter [email protected]. Alle Sicherheitsschwachstellen werden umgehend behoben. Sie können unsere vollständigen Sicherheitsrichtlinien hier einsehen.
Lizenz
PHP dotenv ist lizenziert unter der BSD 3-Clause License.
Für Unternehmen
Erhältlich als Teil des Tidelift-Abonnements