vlucas / phpdotenv

Læsser miljøvariabler fra .env til getenv(), $_ENV og $_SERVER automatisk.

Hvorfor .env?

Du bør aldrig gemme følsomme legitimationsoplysninger i din kode. Lagring af konfiguration i miljøet er et af principperne i en tolv-faktor-app. Alt, der sandsynligvis ændres mellem implementeringsmiljøer – f.eks. databaseoplysninger eller oplysninger om tredjepartstjenester – bør udtrækkes fra koden til miljøvariabler.

En .env-fil er grundlæggende en nem måde at indlæse brugerdefinerede konfigurationsvariabler, som dit program har brug for, uden at skulle ændre .htaccess-filer eller virtuelle værter i Apache/nginx. Det betyder, at du ikke behøver at redigere nogen filer uden for projektet, og at alle miljøvariabler altid er indstillet, uanset hvordan du bruger dit projekt – Apache, Nginx, CLI og endda PHP’s indbyggede webserver. Det er VÆSENTLIGT nemmere end alle de andre måder du kender til at indstille miljøvariabler på, og du vil elske det!

• INGEN redigering af virtuelle værter i Apache eller Nginx
• INGEN tilføjelse af php_valueflag til .htaccess-filer
• Nemmelig portabilitet og deling af nødvendige ENV-værdier
• KOMPATIBEL med PHP’s indbyggede webserver og CLI runner

PHP dotenv er en PHP-version af den originale Rubydotenv.

Installation

Installationen er supernem via Composer:

$ composer require vlucas/phpdotenv

eller tilføj den i hånden til din composer.json fil.

Opgradering

Vi følger semantisk versionering, hvilket betyder, at der kan forekomme breakingchanges mellem større udgivelser. Vi har opgraderingsvejledninger til V2 til V3, V3 til V4 og V4 til V5 tilgængelige her.

Anvendelse

.env-filen holdes generelt uden for versionskontrol, da den kan indeholde følsomme API-nøgler og adgangskoder. Der oprettes en separat .env.example-fil med alle de krævede miljøvariabler defineret med undtagelse af de følsomme, som enten leveres af brugerne til deres egne udviklingsmiljøer eller meddeles andre steder til projektmedarbejdere. Projektmedarbejderne kopierer derefter uafhængigt af hinanden .env.example-filen til en lokal .env og sikrer, at alle indstillingerne er korrekte for deres lokale miljø, idet de udfylder de hemmelige nøgler eller angiver deres egne værdier, hvis det er nødvendigt. I denne brug bør .env-filen tilføjes til projektets .gitignore-fil, så den aldrig vil blive bekræftet af samarbejdspartnere. Denne brug sikrer, at ingen følsomme adgangskoder eller API-nøgler nogensinde vil være i versionsstyringshistorikken, så der er mindre risiko for sikkerhedsbrud, og produktionsværdierne skal aldrig deles med alle projektets samarbejdspartnere.

Føj din programkonfiguration til en .env-fil i roden af dit projekt. Sørg for, at .env-filen er tilføjet til din .gitignore, så den ikke er kontrolleret i koden

S3_BUCKET="dotenv"SECRET_KEY="souper_seekret_key"

Opret nu en fil med navnet .env.example, og check den ind i projektet. Denne skal have de ENV-variabler, du skal have sat, men værdierne skal enten være tomme eller udfyldt med dummy-data. Ideen er at lade folk vide, hvilke variabler der er nødvendige, men ikke at give dem de følsomme produktionsværdier.

S3_BUCKET="devbucket"SECRET_KEY="abc123"

Du kan derefter indlæse .env i dit program med:

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

For at undertrykke den undtagelse, der bliver kastet, når der ikke findes nogen .env-fil, kan du:

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

Optionelt kan du indsætte et filnavn som den anden parameter, hvis du gerne vil bruge noget andet end .env:

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__, 'myconfig');$dotenv->load();

Alle de definerede variabler er nu tilgængelige i $_ENV og $_SERVERsuperglobalerne.

$s3_bucket = $_ENV;$s3_bucket = $_SERVER;

Putenv og Getenv

Brug af getenv() og putenv() frarådes kraftigt, da disse funktioner ikke er trådsikre, men det er dog stadig muligt at instruerePHP dotenv om at bruge disse funktioner. I stedet for at kalde Dotenv::createImmutable kan man kalde Dotenv::createUnsafeImmutable, som vil tilføje PutenvAdapter bag kulisserne. Dine miljøvariabler vil nu være tilgængelige ved hjælp af getenv-metoden, samt super-globalerne:

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

Nesting Variables

Det er muligt at nestre en miljøvariabel i en anden, hvilket er nyttigt for at skære ned på gentagelser.

Dette gøres ved at indpakke en eksisterende miljøvariabel i ${…} f.eks.

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

Immutabilitet og repositorietilpasning

Immutabilitet henviser til, om Dotenv har lov til at overskrive eksisterende miljøvariabler. Hvis du vil have Dotenv til at overskrive eksisterende miljøvariabler, skal du bruge createMutable i stedet for createImmutable:

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

Hinter kulisserne instruerer dette “repository” om at tillade immutabilitet eller ej. Som standard er repositoriet konfigureret til at tillade overskrivning af eksisterendeværdier som standard, hvilket er relevant, hvis man kalder “create”-metoden ved hjælp af RepositoryBuilder for at konstruere et mere brugerdefineret repositorium:

$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();

Overstående eksempel vil skrive indlæste værdier til $_ENV og putenv, men når vi interpolerer miljøvariabler, vil vi kun læse fra $_ENV. Desuden vil det aldrig erstatte variabler, der allerede er indstillet før indlæsning af filen.

Ved hjælp af et andet eksempel kan man også angive et sæt variabler, der skal godkendes som liste. Det vil sige, at kun de variabler på tilladelseslisten vil blive indlæst:

$repository = Dotenv\Repository\RepositoryBuilder::createWithDefaultAdapters() ->allowList() ->make();$dotenv = Dotenv\Dotenv::create($repository, __DIR__);$dotenv->load();

Kræver at variabler skal være indstillet

PHP dotenv har indbygget valideringsfunktionalitet, herunder til at håndhæve tilstedeværelsen af en miljøvariabel. Dette er især nyttigt til at lade folk vide, om der er eksplicit krævede variabler, som din app ikke vil fungere uden.

Du kan bruge en enkelt streng:

$dotenv->required('DATABASE_DSN');

Og et array af strenge:

$dotenv->required();

Hvis der mangler en ENV-variabel, vil Dotenv kaste en RuntimeException som denne:

One or more environment variables failed assertions: DATABASE_DSN is missing

Tomme variabler

Ud over blot at kræve, at en variabel skal være indstillet, kan du også have brug for at sikre, at variablen ikke er tom:

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

Hvis miljøvariablen er tom, får du en undtagelse:

One or more environment variables failed assertions: DATABASE_DSN is empty

Integer Variables

Du skal måske også sikre dig, at variablen har en heltalsværdi. Du kan gøre følgende:

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

Hvis miljøvariablen ikke er et heltal, får du en undtagelse:

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

Det kan være, at man kun ønsker at håndhæve valideringsregler, når en variabel er angivet. Wesunderstøtter også dette:

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

Boolske variabler

Det kan være nødvendigt at sikre, at en variabel er i form af en boolsk variabel, der accepterer “sand”, “falsk”, “On”, “1”, “Ja”, “Off”, “0” og “Nej”. Du kan gøre følgende:

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

Hvis miljøvariablen ikke er en boolean, får du en undtagelse:

One or more environment variables failed assertions: FOO is not a boolean.

Sådan kan man skrive:

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

Tilladte værdier

Det er også muligt at definere et sæt af værdier, som dine miljøvariabler skal være. Dette er især nyttigt i situationer, hvor kun en håndfuld indstillinger eller drivere faktisk understøttes af din kode:

$dotenv->required('SESSION_STORE')->allowedValues();

Hvis miljøvariablen ikke var på denne liste over tilladte værdier, ville du få en lignende undtagelse:

One or more environment variables failed assertions: SESSION_STORE is not an allowed value.

Det er også muligt at definere en regex, som din miljøvariabel skal være.

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

Du kan kommentere din .env fil ved hjælp af #-tegnet. F.eks.

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

Parsing uden indlæsning

I nogle tilfælde vil du bare parse filen og opløse de indlejrede miljøvariabler ved at give os en streng og få et array returneret tilbage til dig. Selv om dette allerede er muligt, er det lidt bøvlet, så vi har givet en direkte måde at gøre dette på:

// Dotenv\Dotenv::parse("FOO=Bar\nBAZ=\"Hello ${FOO}\"");

Dette er præcis det samme som:

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

men i stedet for at angive mappen for at finde filen, har du direkte angivet filens indhold.

Brugsbemærkninger

Når en ny udvikler kloner din kodebase, vil de have et ekstra engangsskridt til manuelt at kopiere .env.example-filen til .env og udfylde deres egne værdier (eller få eventuelle følsomme værdier fra en projektmedarbejder).

Sikkerhed

Hvis du opdager en sikkerhedssårbarhed i denne pakke, bedes du sende en e-mail til Graham Campbell på [email protected]. Alle sikkerhedssårbarheder vil blive behandlet omgående. Du kan se vores fulde sikkerhedspolitik her.

Licens

PHP dotenv er licenseret under The BSD 3-Clause License.

For Enterprise

Fås som en del af Tidelift Subscription