vlucas / phpdotenv

Încarcă automat variabilele de mediu de la .env la getenv(), $_ENV și $_SERVER.

De ce .env?

Nu ar trebui să stocați niciodată credențiale sensibile în codul dumneavoastră. Stocareaconfigurării în mediu este unul dintre principiile unei aplicații cu doisprezece factori. Orice lucru care este posibil să se schimbe între mediile de implementare – cum ar fi acreditările bazei de date sau acreditările pentru servicii de la terți – ar trebui să fie extras din cod în variabile de mediu.

În principiu, un fișier .env este o modalitate ușoară de a încărca variabilele de configurare personalizate de care aplicația dumneavoastră are nevoie fără a fi nevoie să modificați fișierele .htaccess sau gazdele virtuale Apache/nginx. Acest lucru înseamnă că nu va trebui să editați niciun fișier din afara proiectului, iar toate variabilele de mediu sunt întotdeauna setate, indiferent de modul în care văunți proiectul – Apache, Nginx, CLI și chiar serverul web încorporat al PHP. Este FOARTE mai ușor decât toate celelalte modalități pe care le cunoașteți pentru a seta variabilele de mediu,și o să vă placă la nebunie!

• NU editați gazde virtuale în Apache sau Nginx
• NU adăugați stegulețe php_value la .htaccess
• Portabilitate SIMPLĂ și partajare a valorilor ENV necesare
• COMPATIBIL cu serverul web încorporat în PHP și CLI runner

PHP dotenv este o versiune PHP a originalului Rubydotenv.

Instalare

Instalarea este super-ușoară prin Composer:

$ composer require vlucas/phpdotenv

sau adăugați-l manual în fișierul composer.json.

Actualizare

Apăstrăm versiuni semantice, ceea ce înseamnă că pot apărea modificări de întrerupere între versiunile majore. Avem ghiduri de actualizare disponibilepentru V2 la V3, V3 la V4 și V4 la V5 disponibile aici.

Utilizare

Fileul .env este în general ținut în afara controlului versiunilor deoarece poate conține chei și parole API sensibile. Se creează un fișier separat .env.examplecu toate variabilele de mediu necesare definite, cu excepția celor sensibile, care fie sunt furnizate de utilizator pentru propriile medii de dezvoltare, fie sunt comunicate în altă parte colaboratorilor proiectului. Colaboratorii proiectului copiază apoi în mod independent fișierul .env.example într-un .env local și se asigură că toate setările sunt corecte pentru mediul lor local, completând cheile secrete sau furnizând propriile valori atunci când este necesar. În această utilizare, fișierul .env ar trebui să fie adăugat la fișierul .gitignore al proiectului, astfel încât să nu fie niciodată confirmat de către colaboratori. Această utilizare asigură că nici o parolă sau cheie API sensibilă nu se va afla vreodată în istoricul de control al versiunilor, astfel încât există un risc mai mic de breșă de securitate, iar valorile de producție nu vor trebui niciodată să fie împărtășite cu toți colaboratorii proiectului.

Adaugați configurația aplicației dvs. la un fișier .env în rădăcina proiectului. Asigurați-vă că fișierul .env este adăugat la .gitignore, astfel încât să nu fie verificat în cod

S3_BUCKET="dotenv"SECRET_KEY="souper_seekret_key"

Cresați acum un fișier numit .env.example și verificați-l în proiect. Acesta ar trebui să conțină variabilele ENV pe care trebuie să le aveți setate, dar valorile ar trebui să fie fie goale sau completate cu date fictive. Ideea este de a lăsa oamenii să știe ce variabile sunt necesare, dar nu de a le da valorile sensibile de producție.

S3_BUCKET="devbucket"SECRET_KEY="abc123"

Puteți apoi încărca .env în aplicația dvs. cu:

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

Pentru a suprima excepția care este aruncată atunci când nu există un fișier .env, puteți:

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

Opțional, puteți trece un nume de fișier ca al doilea parametru, dacă doriți să folosiți altceva decât .env:

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

Toate variabilele definite sunt acum disponibile în $_ENV și $_SERVERsuper-globals.

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

Putenv și Getenv

Utilizarea funcțiilor getenv() și putenv() este puternic descurajată din cauza faptului căaceste funcții nu sunt sigure pentru fire de execuție, cu toate acestea este încă posibil să se instruiascăPHP dotenv să utilizeze aceste funcții. În loc de a apelaDotenv::createImmutable, se poate apela Dotenv::createUnsafeImmutable, care va adăuga PutenvAdapter în spatele scenei. Variabilele de mediu vor fi acum disponibile folosind metoda getenv, precum și superglobalele:

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

Anidarea variabilelor

Este posibil să se anideze o variabilă de mediu în alta, util pentru a reduce repetițiile.

Acest lucru se face prin înglobarea unei variabile de mediu existente în ${…}, de exemplu:

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

Imutabilitatea și personalizarea depozitului

Imutabilitatea se referă la faptul dacă Dotenv are voie să suprascrie variabilele de mediu existente. Dacă doriți ca Dotenv să suprascrie variabilele de mediu existente,utilizați createMutable în loc de createImmutable:

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

În spatele scenei, acest lucru instruiește „depozitul” să permită sau nu imutabilitatea. În mod implicit, depozitul este configurat pentru a permite suprascrierea valorilor existente în mod implicit, ceea ce este relevant dacă se apelează metoda „create” folosind RepositoryBuilder pentru a construi un depozit mai personalizat:

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

Exemplul de mai sus va scrie valorile încărcate în $_ENV și putenv, dar atunci cândinterpolăm variabilele de mediu, vom citi doar din $_ENV. Mai mult, nu va înlocui niciodată variabilele deja setate înainte de a încărca fișierul.

Prin intermediul unui alt exemplu, se poate specifica, de asemenea, un set de variabile care să nu poată fi listate. Adică, doar variabilele din lista permisă vor fi încărcate:

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

Solicitarea setării variabilelor

PHP dotenv are încorporată o funcționalitate de validare, inclusiv pentru impunerea prezenței unei variabile de mediu. Acest lucru este deosebit de util pentru a permite oamenilor să cunoască orice variabile cerute explicit fără de care aplicația dumneavoastră nu va funcționa.

Puteți folosi un singur șir de caractere:

$dotenv->required('DATABASE_DSN');

Sau o matrice de șiruri de caractere:

$dotenv->required();

Dacă lipsește vreo variabilă ENV, Dotenv va arunca un RuntimeException ca acesta:

One or more environment variables failed assertions: DATABASE_DSN is missing

Variabile goale

Pe lângă simpla cerință ca o variabilă să fie setată, este posibil să aveți nevoie să vă asigurați că variabila nu este goală:

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

Dacă variabila de mediu este goală, veți obține o excepție:

One or more environment variables failed assertions: DATABASE_DSN is empty

Variabile întregi

De asemenea, ar putea fi necesar să vă asigurați că variabila are o valoare întreagă. Putețiface următoarele:

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

Dacă variabila de mediu nu este un număr întreg, veți obține o excepție:

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

Se poate dori să se aplice regulile de validare numai atunci când o variabilă este setată. Wesuportă și acest lucru:

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

Variabile booleene

Poate fi nevoie să vă asigurați că o variabilă este sub forma unui boolean, acceptând „true”, „false”, „On”, „1”, „Yes”, „Off”, „0” și „No”. Puteți face următoarele:

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

Dacă variabila de mediu nu este un boolean, veți obține o excepție:

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

În mod similar, se poate scrie:

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

Valori permise

De asemenea, este posibil să definiți un set de valori pe care variabilele de mediu ar trebui să le aibă. Acest lucru este deosebit de util în situațiile în care doar o mână deopțiuni sau drivere sunt suportate efectiv de codul dumneavoastră:

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

Dacă variabila de mediu nu se afla în această listă de valori permise, veți obține o excepție asemănătoare:

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

De asemenea, este posibil să definiți un regex care ar trebui să fie variabila dumneavoastră de mediu.

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

Vă puteți comenta fișierul .env folosind caracterul #. De exemplu:

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

Parsarea fără încărcare

Câteodată vreți doar să analizați fișierul și să rezolvați variabilele de mediu imbricate, dându-ne un șir de caractere și să vi se returneze o matrice. Deși acest lucru este deja posibil, este un pic cam complicat, așa că am oferit o modalitate directă de a face acest lucru:

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

Este exact la fel ca:

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

Doar că, în loc să furnizați directorul pentru a găsi fișierul, ați furnizat direct conținutul fișierului.

Note de utilizare

Când un nou dezvoltator vă clonează baza de cod, acesta va trebui să facă un pas suplimentar de o singură dată pentru a copia manual fișierul .env.example în .env și să completeze propriile valori (sau să obțină orice valori sensibile de la un coleg de proiect).

Securitate

Dacă descoperiți o vulnerabilitate de securitate în cadrul acestui pachet, vă rugăm să trimiteți un e-mail către Graham Campbell la [email protected]. Toate vulnerabilitățile de securitate vor fi rezolvate cu promptitudine. Puteți vizualiza politica noastră completă de securitate aici.

Licență

PHP dotenv este licențiat sub licența BSD 3-Clause License.

For Enterprise

Disponibil ca parte a Abonamentului Tidelift

.