Laddar automatiskt miljövariabler från .env till getenv(), $_ENV och $_SERVER.
Varför .env?
Du bör aldrig lagra känsliga autentiseringsuppgifter i din kod. Att lagra konfigurationen i miljön är en av grundprinciperna för en tolvfaktorsapplikation. Allt som sannolikt kommer att ändras mellan olika distributionsmiljöer – t.ex. databasreferenser eller referenser för tredjepartstjänster – bör extraheras från koden till miljövariabler.
En .env-fil är i grund och botten ett enkelt sätt att ladda in anpassade konfigurationsvariabler som programmet behöver utan att behöva ändra .htaccess-filer eller virtuella värdar i Apache/nginx. Detta innebär att du inte behöver redigera några filer utanför projektet och att alla miljövariabler alltid är inställda oavsett hur ditt projekt är uppbyggt – Apache, Nginx, CLI och till och med PHP:s inbyggda webbserver. Det är VÄLDIGT enklare än alla andra sätt du känner till för att ställa in miljövariabler, och du kommer att älska det!
- INGEN redigering av virtuella värdar i Apache eller Nginx
- INGEN tillägg av
php_value-flaggor till .htaccess-filer - Enklare portabilitet och delning av nödvändiga ENV-värden
- KOMPATIBEL med PHP:s inbyggda webbserver och CLI runner
PHP dotenv är en PHP-version av den ursprungliga Rubydotenv.
Installation
Installationen är superenkel via Composer:
$ composer require vlucas/phpdotenv
eller lägg till den för hand i din composer.json-fil.
Uppgradering
Vi följer semantisk versionshantering, vilket innebär att brytandeändringar kan förekomma mellan större versioner. Vi har uppgraderingsguider för V2 till V3, V3 till V4 och V4 till V5 tillgängliga här.
Användning
.env-filen hålls vanligtvis utanför versionskontrollen eftersom den kan innehålla känsliga API-nycklar och lösenord. En separat .env.example-fil skapas med alla nödvändiga miljövariabler definierade utom de känsliga, som antingen tillhandahålls av användarna för deras egna utvecklingsmiljöer eller meddelas på annat sätt till projektmedarbetare. Projektmedarbetarna kopierar sedan självständigt .env.example-filen till en lokal .env och ser till att alla inställningar är korrekta för deras lokala miljö, genom att fylla i de hemliga nycklarna eller tillhandahålla egna värden vid behov. Vid denna användning bör .env-filen läggas till i projektets .gitignore-fil så att den aldrig kommer att överföras av samarbetspartnerna. Denna användning säkerställer att inga känsliga lösenord eller API-nycklar någonsin kommer att finnas i versionshistoriken, vilket minskar risken för säkerhetsöverträdelser, och att produktionsvärden aldrig behöver delas med alla projektmedarbetare.
Lägg till programkonfigurationen i en .env-fil i roten av ditt projekt. Se till att .env-filen läggs till i din .gitignore så att den inte kontrolleras i koden
S3_BUCKET="dotenv"SECRET_KEY="souper_seekret_key"
Skapa nu en fil som heter .env.example och checka in den i projektet. Den ska ha de ENV-variabler som du behöver ställa in, men värdena ska antingen vara tomma eller fyllda med dummy-data. Tanken är att låta folk veta vilka variabler som krävs, men inte ge dem de känsliga produktionsvärdena.
S3_BUCKET="devbucket"SECRET_KEY="abc123"
Du kan sedan ladda .env i ditt program med:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);$dotenv->load();
För att undertrycka undantaget som kastas när det inte finns någon .env-fil kan du:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);$dotenv->safeLoad();
Optionellt kan du skicka in ett filnamn som den andra parametern, om du vill använda något annat än .env:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__, 'myconfig');$dotenv->load();
Alla definierade variabler finns nu tillgängliga i $_ENV och $_SERVERsuperglobalerna.
$s3_bucket = $_ENV;$s3_bucket = $_SERVER;
Putenv och Getenv
Användning av getenv() och putenv() avråds starkt på grund av att dessa funktioner inte är trådsäkra, men det är fortfarande möjligt att instrueraPHP dotenv att använda dessa funktioner. Istället för att anropa Dotenv::createImmutable kan man anropa Dotenv::createUnsafeImmutable, som kommer att lägga till PutenvAdapter bakom kulisserna. Dina miljövariabler kommer nu att vara tillgängliga med hjälp av getenv-metoden, liksom superglobalerna:
$s3_bucket = getenv('S3_BUCKET');$s3_bucket = $_ENV;$s3_bucket = $_SERVER;
Nesting Variables
Det är möjligt att nästla in en miljövariabel i en annan, vilket är användbart för att minska på upprepningar.
Detta görs genom att omsluta en befintlig miljövariabel i ${…} t.ex.
BASE_DIR="/var/webroot/project-root"CACHE_DIR="${BASE_DIR}/cache"TMP_DIR="${BASE_DIR}/tmp"
Immutabilitet och anpassning av förvaringsutrymmen
Immutabilitet avser om Dotenv tillåts skriva över befintliga miljövariabler. Om du vill att Dotenv ska skriva över befintliga miljövariabler, använd createMutable istället för createImmutable:
$dotenv = Dotenv\Dotenv::createMutable(__DIR__);$dotenv->load();
Här bakom kulisserna instruerar detta ”repository” att tillåta immutabilitet eller inte. Som standard är repositoriet konfigurerat för att tillåta överskrivning av befintliga värden, vilket är relevant om man anropar ”create”-metoden med RepositoryBuilder för att konstruera ett mer anpassat 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();
Ovanstående exempel kommer att skriva inlästa värden till $_ENV och putenv, men när vi interpolerar miljövariabler läser vi bara från $_ENV. Dessutom kommer det aldrig att ersätta variabler som redan var inställda innan filen laddades.
Med hjälp av ett annat exempel kan man också ange en uppsättning variabler som ska tillåtas listas. Det innebär att endast variablerna i listan kommer att laddas:
$repository = Dotenv\Repository\RepositoryBuilder::createWithDefaultAdapters() ->allowList() ->make();$dotenv = Dotenv\Dotenv::create($repository, __DIR__);$dotenv->load();
Krav på att variabler ska sättas
PHP dotenv har inbyggd valideringsfunktionalitet, bland annat för att tvinga fram närvaron av en miljövariabel. Detta är särskilt användbart för att låta folk få veta om det finns explicita variabler som krävs och som din app inte kommer att fungera utan.
Du kan använda en enda sträng:
$dotenv->required('DATABASE_DSN');
Och en array av strängar:
$dotenv->required();
Om någon ENV-variabel saknas kommer Dotenv att kasta en RuntimeException så här:
One or more environment variables failed assertions: DATABASE_DSN is missingTomma variabler
Förutom att kräva att en variabel ska vara inställd kan du också behöva se till att variabeln inte är tom:
$dotenv->required('DATABASE_DSN')->notEmpty();
Om miljövariabeln är tom får du ett undantag:
One or more environment variables failed assertions: DATABASE_DSN is emptyHela variabler
Du kan också behöva försäkra dig om att variabeln har ett heltalsvärde. Du kan göra följande:
$dotenv->required('FOO')->isInteger();
Om miljövariabeln inte är ett heltal får du ett undantag:
One or more environment variables failed assertions: FOO is not an integer.Det kan hända att man bara vill tillämpa valideringsregler när en variabel är inställd. Wes har stöd för detta också:
$dotenv->ifPresent('FOO')->isInteger();
Boolska variabler
Du kan behöva se till att en variabel är i form av en boolsk variabel som accepterar ”true”, ”false”, ”On”, ”1”, ”Yes”, ”Off”, ”0” och ”No”. Du kan göra följande:
$dotenv->required('FOO')->isBoolean();
Om miljövariabeln inte är en boolean får du ett undantag:
One or more environment variables failed assertions: FOO is not a boolean.Samma kan man skriva:
$dotenv->ifPresent('FOO')->isBoolean();
Tillåtna värden
Det är också möjligt att definiera en uppsättning värden som miljövariablerna ska ha. Detta är särskilt användbart i situationer där endast en handfull alternativ eller drivrutiner stöds av din kod:
$dotenv->required('SESSION_STORE')->allowedValues();
Om miljövariabeln inte finns med i listan över tillåtna värden får du ett liknande undantag:
One or more environment variables failed assertions: SESSION_STORE is not an allowed value.Det är också möjligt att definiera ett regex som miljövariabeln ska vara.
$dotenv->required('FOO')->allowedRegexValues('(]{3})');
Du kan kommentera din .env-fil med hjälp av tecknet #. T.ex.
# this is a commentVAR="value" # commentVAR=value # comment
Parsing Without Loading
Ibland vill du bara parsa filen och lösa upp de inbäddade miljövariablerna, genom att ge oss en sträng och få en array returnerad till dig. Även om detta redan är möjligt är det lite krångligt, så vi har tillhandahållit ett direkt sätt att göra detta:
// Dotenv\Dotenv::parse("FOO=Bar\nBAZ=\"Hello ${FOO}\"");
Detta är exakt samma sak som:
Dotenv\Dotenv::createArrayBacked(__DIR__)->load();
när du i stället för att ange katalogen för att hitta filen, har du direkt angett filinnehållet.
Användningsanmärkningar
När en ny utvecklare klonar din kodbas kommer de att ha ett extra engångssteg för att manuellt kopiera .env.example-filen till .env och fylla i sina egna värden (eller få känsliga värden från en projektkollega).
Säkerhet
Om du upptäcker en säkerhetssårbarhet i det här paketet, vänligen skicka ett mail till Graham Campbell på [email protected]. Alla säkerhetssårbarheter kommer att åtgärdas omgående. Du kan se vår fullständiga säkerhetspolicy här.
Licens
PHP dotenv är licensierat under BSD 3-Clause License.
For Enterprise
Försvaras som en del av Tidelift Subscription