phpdotenv

PHP dotenv

Lädt Umgebungsvariablen automatisch von .env nach getenv() , $_ENV und $_SERVER .

Warum .env?

Sie sollten niemals vertrauliche Anmeldeinformationen in Ihrem Code speichern . Das Speichern der Konfiguration in der Umgebung ist einer der Grundsätze einer Zwölf-Faktor-App. Alles, was sich wahrscheinlich zwischen den Bereitstellungsumgebungen ändert – wie Datenbankanmeldeinformationen oder Anmeldeinformationen 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 .htaccess-Dateien oder virtuelle Apache/Nginx-Hosts ändern zu müssen. Das bedeutet, dass Sie keine Dateien außerhalb des Projekts bearbeiten müssen und alle Umgebungsvariablen immer gesetzt sind, egal wie Sie Ihr Projekt ausführen – Apache, Nginx, CLI und sogar der integrierte Webserver von PHP. Es ist VIEL einfacher als alle anderen Möglichkeiten, Umgebungsvariablen festzulegen, und Sie werden es lieben!

• KEINE Bearbeitung virtueller Hosts in Apache oder Nginx
• KEIN Hinzufügen php_value Flags zu .htaccess-Dateien
• EINFACHE Portabilität und gemeinsame Nutzung der erforderlichen ENV-Werte
• KOMPATIBEL mit dem integrierten Webserver und CLI-Runner von PHP

PHP dotenv ist eine PHP-Version des ursprünglichen Ruby dotenv.

Installation

Die Installation ist über Composer ganz einfach:

$ composer require vlucas/phpdotenv

oder fügen Sie es manuell zu Ihrer composer.json Datei hinzu.

Upgrade

Wir folgen der semantischen Versionierung, was bedeutet, dass es zwischen Hauptversionen zu wichtigen Änderungen kommen kann. Hier finden Sie Upgrade-Anleitungen für V2 auf V3, V3 auf V4 und V4 auf V5.

Verwendung

Die .env Datei unterliegt im Allgemeinen keiner Versionskontrolle, da sie vertrauliche 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 vom Benutzer für ihre eigenen Entwicklungsumgebungen bereitgestellt oder an anderer Stelle an Projektmitarbeiter kommuniziert 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 eingeben oder bei Bedarf ihre eigenen Werte bereitstellen. Bei dieser Verwendung sollte die .env Datei zur .gitignore Datei des Projekts hinzugefügt werden, damit sie niemals von Mitarbeitern übernommen wird. Durch diese Verwendung wird sichergestellt, dass sich niemals vertrauliche Passwörter oder API-Schlüssel im Versionskontrollverlauf befinden, sodass das Risiko einer Sicherheitsverletzung geringer ist und Produktionswerte niemals mit allen Projektbeteiligten geteilt werden müssen.

Fügen Sie Ihre Anwendungskonfiguration einer .env Datei im Stammverzeichnis Ihres Projekts hinzu. Stellen Sie sicher, dass die .env Datei zu Ihrem .gitignore hinzugefügt wird, damit sie nicht im Code eingecheckt wird

S3_BUCKET= " dotenv "
SECRET_KEY= " souper_seekret_key "

Erstellen Sie nun eine Datei mit dem Namen .env.example und checken Sie diese in das Projekt ein. Hier sollten die ENV-Variablen vorhanden sein, die Sie festlegen müssen, die Werte sollten jedoch entweder leer oder mit Dummy-Daten gefüllt sein. Die Idee besteht darin, den Menschen mitzuteilen, welche Variablen erforderlich sind, ihnen jedoch nicht die sensiblen Produktionswerte zu geben.

S3_BUCKET= " devbucket "
SECRET_KEY= " abc123 "

Anschließend können Sie .env in Ihre Anwendung laden mit:

 $ dotenv = Dotenv  Dotenv :: createImmutable ( __DIR__ );
$ dotenv -> load ();

Um die Ausnahme zu unterdrücken, die ausgelöst wird, wenn keine .env Datei vorhanden ist, können Sie Folgendes tun:

 $ dotenv = Dotenv  Dotenv :: createImmutable ( __DIR__ );
$ dotenv -> safeLoad ();

Optional können Sie als zweiten Parameter einen Dateinamen ü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 Superglobals $_ENV und $_SERVER verfügbar.

 $ s3_bucket = $ _ENV [ ' S3_BUCKET ' ];
$ s3_bucket = $ _SERVER [ ' S3_BUCKET ' ];

Putenv und Getenv

Von der Verwendung von getenv() und putenv() wird dringend abgeraten, da diese Funktionen nicht threadsicher sind. Es ist jedoch dennoch möglich, PHP dotenv anzuweisen, diese Funktionen zu verwenden. Anstatt Dotenv::createImmutable aufzurufen, kann man Dotenv::createUnsafeImmutable aufrufen, wodurch der PutenvAdapter im Hintergrund hinzugefügt wird. Ihre Umgebungsvariablen sowie die Superglobals sind jetzt mit der getenv -Methode verfügbar:

 $ s3_bucket = getenv ( ' S3_BUCKET ' );
$ s3_bucket = $ _ENV [ ' S3_BUCKET ' ];
$ s3_bucket = $ _SERVER [ ' S3_BUCKET ' ];

Verschachtelungsvariablen

Es ist möglich, eine Umgebungsvariable in einer anderen zu verschachteln, um Wiederholungen zu vermeiden.

Dies geschieht durch Einschließen einer vorhandenen Umgebungsvariablen in ${…} z. B

BASE_DIR= " /var/webroot/project-root "
CACHE_DIR= " ${BASE_DIR} /cache "
TMP_DIR= " ${BASE_DIR} /tmp "

Unveränderlichkeit und Repository-Anpassung

Unveränderlichkeit bezieht sich darauf, ob Dotenv vorhandene Umgebungsvariablen überschreiben darf. Wenn Sie möchten, dass Dotenv vorhandene Umgebungsvariablen überschreibt, verwenden Sie createMutable anstelle von createImmutable :

 $ dotenv = Dotenv  Dotenv :: createMutable ( __DIR__ );
$ dotenv -> load ();

Hinter den Kulissen weist dies das „Repository“ an, Unveränderlichkeit zuzulassen oder nicht. Standardmäßig ist das Repository so konfiguriert, dass standardmäßig vorhandene Werte überschrieben werden können. Dies ist relevant, wenn die Methode „create“ mit dem RepositoryBuilder aufgerufen wird, um ein individuelleres 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 . Darüber hinaus werden niemals Variablen ersetzt, die bereits vor dem Laden der Datei festgelegt wurden.

Anhand eines anderen Beispiels kann man auch einen Satz von Variablen angeben, die zugelassen werden sollen. Das heißt, es werden nur die Variablen in der Zulassungsliste geladen:

 $ repository = Dotenv  Repository  RepositoryBuilder :: createWithDefaultAdapters ()
    -> allowList ([ ' FOO ' , ' BAR ' ])
    -> make ();

$ dotenv = Dotenv  Dotenv :: create ( $ repository , __DIR__ );
$ dotenv -> load ();

Es müssen Variablen festgelegt werden

PHP dotenv verfügt über eine integrierte Validierungsfunktion, unter anderem zum Erzwingen des Vorhandenseins einer Umgebungsvariablen. Dies ist besonders nützlich, um die Leute über alle explizit erforderlichen Variablen zu informieren, ohne die Ihre App nicht funktionieren würde.

Sie können eine einzelne Zeichenfolge verwenden:

 $ dotenv -> required ( ' DATABASE_DSN ' );

Oder ein Array von Strings:

 $ dotenv -> required ([ ' DB_HOST ' , ' DB_NAME ' , ' DB_USER ' , ' DB_PASS ' ]);

Wenn ENV-Variablen fehlen, löst Dotenv eine RuntimeException wie diese aus:

 One or more environment variables failed assertions: DATABASE_DSN is missing

Leere Variablen

Neben der bloßen Anforderung, dass eine Variable festgelegt werden muss, müssen Sie möglicherweise auch sicherstellen, dass die Variable nicht leer ist:

 $ dotenv -> required ( ' DATABASE_DSN ' )-> notEmpty ();

Wenn die Umgebungsvariable leer ist, erhalten Sie eine Ausnahme:

 One or more environment variables failed assertions: DATABASE_DSN is empty

Ganzzahlige Variablen

Möglicherweise müssen Sie auch sicherstellen, dass die Variable einen ganzzahligen Wert hat. Sie können Folgendes tun:

 $ dotenv -> required ( ' FOO ' )-> isInteger ();

Wenn die Umgebungsvariable keine Ganzzahl ist, erhalten Sie eine Ausnahme:

 One or more environment variables failed assertions: FOO is not an integer.

Möglicherweise möchte man Validierungsregeln nur dann erzwingen, wenn eine Variable festgelegt ist. Auch das unterstützen wir:

 $ dotenv -> ifPresent ( ' FOO ' )-> isInteger ();

Boolesche Variablen

Möglicherweise müssen Sie sicherstellen, dass eine Variable die Form eines booleschen Werts hat und „wahr“, „falsch“, „Ein“, „1“, „Ja“, „Aus“, „0“ und „Nein“ akzeptiert. Sie können Folgendes tun:

 $ 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.

Ebenso könnte man schreiben:

 $ dotenv -> ifPresent ( ' FOO ' )-> isBoolean ();

Zulässige Werte

Es ist auch möglich, eine Reihe von Werten zu definieren, die Ihre Umgebungsvariable haben soll. Dies ist besonders nützlich in Situationen, in denen nur eine Handvoll Optionen oder Treiber tatsächlich von Ihrem Code unterstützt werden:

 $ dotenv -> required ( ' SESSION_STORE ' )-> allowedValues ([ ' Filesystem ' , ' Memcached ' ]);

Wenn die Umgebungsvariable nicht in dieser Liste zulässiger 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, einen regulären Ausdruck zu definieren, der Ihre Umgebungsvariable sein soll.

 $ dotenv -> required ( ' FOO ' )-> allowedRegexValues ( ' ([[:lower:]]{3}) ' );

Kommentare

Sie können Ihre .env Datei mit dem Zeichen # kommentieren. Z.B

 # this is a comment
VAR= " value " # comment
VAR=value # comment

Parsen ohne Laden

Manchmal möchten Sie einfach die Datei analysieren und die verschachtelten Umgebungsvariablen auflösen, indem Sie uns eine Zeichenfolge übergeben und ein Array an Sie zurückgeben. Obwohl dies bereits möglich ist, ist es etwas umständlich. Deshalb haben wir eine direkte Möglichkeit bereitgestellt, dies zu tun:

 // ['FOO' => 'Bar', 'BAZ' => 'Hello Bar']
Dotenv  Dotenv :: parse ( " FOO=Bar n BAZ= " Hello $ {FOO} "" );

Das ist genau das Gleiche wie:

 Dotenv  Dotenv :: createArrayBacked ( __DIR__ )-> load ();

Anstatt jedoch das Verzeichnis zum Auffinden der Datei anzugeben, haben Sie direkt den Dateiinhalt angegeben.

Nutzungshinweise

Wenn ein neuer Entwickler Ihre Codebasis klont, muss er als zusätzlicher einmaliger Schritt die Datei .env.example manuell nach .env kopieren und seine eigenen Werte eingeben (oder vertrauliche Werte von einem Projektmitarbeiter erhalten).

Fehlerbehebung

In bestimmten Server-Setups (am häufigsten beim Shared Hosting zu finden) deaktiviert PHP möglicherweise Superglobals wie $_ENV oder $_SERVER . Wenn diese Variablen nicht festgelegt sind, überprüfen Sie die variables_order in der Datei php.ini . Siehe php.net/manual/en/ini.core.php#ini.variables-order.

Sicherheit

Wenn Sie eine Sicherheitslücke in diesem Paket entdecken, senden Sie bitte eine E-Mail an [email protected]. Alle Sicherheitslücken werden umgehend behoben. Unsere vollständige Sicherheitsrichtlinie können Sie hier einsehen.

Lizenz

PHP dotenv ist unter der BSD 3-Clause-Lizenz lizenziert.

Für Unternehmen

Verfügbar als Teil des Tidelift-Abonnements

Die Betreuer von vlucas/phpdotenv und Tausenden anderer Pakete arbeiten mit Tidelift zusammen, um kommerziellen Support und Wartung für die Open-Source-Abhängigkeiten bereitzustellen, die Sie zum Erstellen Ihrer Anwendungen verwenden. Sparen Sie Zeit, reduzieren Sie Risiken und verbessern Sie den Zustand des Codes, während Sie gleichzeitig die Betreuer der genauen Abhängigkeiten bezahlen, die Sie verwenden. Erfahren Sie mehr.