vlucas / phpdotenv

Lataa ympäristömuuttujat .env:stä getenv():een, $_ENV:een ja $_SERVER:een automaattisesti.

Miksi .env:stä?

Koodissasi ei koskaan saisi tallettaa arkaluontoisia tunnuksia. Konfiguraation tallentaminen ympäristöön on yksi kahdentoista tekijän sovelluksen periaatteista. Kaikki, mikä todennäköisesti muuttuu käyttöönottoympäristöjen välillä – kuten tietokantatunnukset tai kolmannen osapuolen palveluiden tunnukset – tulisi purkaa koodista ympäristömuuttujiin.

Periaatteessa .env-tiedosto on helppo tapa ladata sovelluksesi tarvitsemat mukautetut konfiguraatiomuuttujat ilman, että joudut muokkaamaan .htaccess-tiedostoja tai Apache/nginx-virtuaali-isäntiä. Tämä tarkoittaa, että sinun ei tarvitse muokata mitään tiedostoja projektin ulkopuolella, ja kaikki ympäristömuuttujat ovat aina asetettu riippumatta siitä, miten projektisi käynnistät – Apache, Nginx, CLI ja jopa PHP:n sisäänrakennettu verkkopalvelin. Se on AIVAN helpompaa kuin kaikki muut tuntemasi tavat asettaa ympäristömuuttujia,ja tulet rakastamaan sitä!

• Ei virtuaalisten isäntien muokkaamista Apachessa tai Nginxissä
• Ei php_value-lippujen lisäämistä .htaccess-tiedostoihin
• Helppo siirrettävyys ja tarvittavien ENV-arvojen jakaminen
• YHTEENSOPIVA PHP:n sisäänrakennetun web-palvelimen ja CLI-runnerin kanssa

PHP dotenv on PHP-versio alkuperäisestä Rubydotenvistä.

Asennus

Asennus on superhelppo Composerin kautta:

$ composer require vlucas/phpdotenv

tai lisää se käsin composer.json-tiedostoosi.

Päivitykset

Noudatamme semanttista versionhallintaa, mikä tarkoittaa, että rikkovia muutoksia voi tapahtua suurempien versioiden välillä. Meillä on päivitysoppaita saatavilla V2:sta V3:een, V3:sta V4:ään ja V4:stä V5:een täällä.

Käyttö

.env-tiedosto pidetään yleensä versionhallinnan ulkopuolella, koska se voi sisältää arkaluontoisia API-avaimia ja salasanoja. Luodaan erillinen .env.example-tiedosto, jossa on määritetty kaikki tarvittavat ympäristömuuttujat lukuun ottamatta arkaluonteisia muuttujia, jotka käyttäjä joko antaa omiin kehitysympäristöihinsä tai jotka ilmoitetaan muualla projektin yhteistyökumppaneille. Projektin yhteistyökumppanit kopioivat sitten itsenäisesti .env.example-tiedoston paikalliseen .env-tiedostoon ja varmistavat, että kaikki asetukset ovat paikallisen ympäristönsä kannalta oikeat, täyttämällä salaiset avaimet tai antamalla tarvittaessa omat arvonsa. Tässä käytössä .env-tiedosto olisi lisättävä projektin .gitignore-tiedostoon, jotta yhteistyökumppanit eivät koskaan luovuta sitä. Tämä käyttö varmistaa, ettei arkaluonteisia salasanoja tai API-avaimia koskaan ole versionhallintahistoriassa, joten tietoturvaloukkauksen riski on pienempi, eikä tuotantoarvoja tarvitse koskaan jakaa kaikkien projektin yhteistyökumppaneiden kanssa.

Lisää sovelluksen konfiguraatioita .env-tiedostoon projektin juuressa. Varmista, että .env-tiedosto on lisätty .gitignore:iin, jotta sitä ei tarkisteta koodissa

S3_BUCKET="dotenv"SECRET_KEY="souper_seekret_key"

Luo nyt tiedosto nimeltä .env.example ja tarkista se projektiin. Siinä pitäisi olla ne ENV-muuttujat, jotka sinun on asetettava, mutta arvojen pitäisi olla joko tyhjiä tai täytetty tyhjillä tiedoilla. Ajatuksena on kertoa ihmisille, mitä muuttujia tarvitaan, mutta ei antaa heille herkkiä tuotantoarvoja.

S3_BUCKET="devbucket"SECRET_KEY="abc123"

Voit sitten ladata .env sovellukseesi:

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

Voit estää poikkeuksen, joka heitetään, kun .env-tiedostoa ei ole, seuraavasti:

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

Vaihtoehtoisesti voit antaa toisena parametrina tiedostonimen, jos haluat käyttää jotain muuta kuin .env:

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

Kaikki määritellyt muuttujat ovat nyt käytettävissä $_ENV– ja $_SERVERsuper-globaalissa.

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

Putenv ja Getenv

getenv() ja putenv() käyttämistä ei suositella, koska nämä funktiot eivät ole säikeenkestäviä, muttaPHP dotenv:tä on kuitenkin mahdollista ohjeistaa käyttämään näitä funktioita. Sen sijaan, että kutsutaan Dotenv::createImmutable, voidaan kutsua Dotenv::createUnsafeImmutable, joka lisää PutenvAdapter kulissien takana. Ympäristömuuttujasi ovat nyt käytettävissä getenv-menetelmällä, samoin kuin super-globaalit:

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

Muuttujien pesäyttäminen

Ympäristömuuttujaa on mahdollista pesäyttää toisen ympäristömuuttujan sisälle, mikä on hyödyllistä, kun halutaan vähentää toistoa.

Tämä tehdään kietomalla olemassa oleva ympäristömuuttuja ${…}:n sisään esim.

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

Muuttumattomuus ja säilytyspaikan mukauttaminen

Muuttumattomuudella tarkoitetaan sitä, saako Dotenv korvata olemassa olevia ympäristömuuttujia. Jos haluat Dotenv:n ylikirjoittavan olemassa olevat ympäristömuuttujat,käytä createImmutable:n sijasta createMutable:

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

Takana kulisseissa tämä ohjeistaa ”arkistoa” sallimaan muuttumattomuudentai ei. Oletusarvoisesti repository on konfiguroitu niin, että se sallii oletusarvoisesti olemassa olevienarvojen ylikirjoittamisen, mikä on merkityksellistä, jos kutsutaan ”create”-metodia käyttäen RepositoryBuilder rakentaaksemme räätälöidymmän repository:

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

Ylläoleva esimerkki kirjoittaa ladatut arvot $_ENV:een ja putenv:een, mutta interpoloitaessa ympäristömuuttujia luemme vain $_ENV:sta. Lisäksi se ei koskaan korvaa muuttujia, jotka on jo asetettu ennen tiedoston lataamista.

Toisen esimerkin avulla voidaan myös määritellä joukko muuttujia, jotka voidaan sallia listata. Toisin sanoen vain sallitun listan muuttujat ladataan:

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

Muuttujien asettamisen vaatiminen

PHP dotenv:ssä on sisäänrakennettu validointitoiminnallisuus, myös ympäristömuuttujan läsnäolon pakottamiseksi. Tämä on erityisen hyödyllistä, jotta ihmiset tietävät kaikki nimenomaisesti vaaditut muuttujat, joita ilman sovelluksesi ei toimi.

Voit käyttää yksittäistä merkkijonoa:

$dotenv->required('DATABASE_DSN');

Vai merkkijonojen joukkoa:

$dotenv->required();

Jos jokin ENV-tavaroista puuttuu, Dotenv heittää RuntimeException kuten tämä:

One or more environment variables failed assertions: DATABASE_DSN is missing

Tyhjät muuttujat

Muuttujan asettamisen vaatimisen lisäksi sinun on ehkä myös varmistettava, ettei muuttuja ole tyhjä:

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

Jos ympäristömuuttuja on tyhjä, saat poikkeuksen:

One or more environment variables failed assertions: DATABASE_DSN is empty

Kokonaislukumuuttujat

Voi myös olla tarpeen varmistaa, että muuttujalla on kokonaislukuarvo. Voittehdä seuraavaa:

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

Jos ympäristömuuttuja ei ole kokonaisluku, saatte Poikkeuksen:

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

Voi olla, että haluatte valvoa validointisääntöjä vain silloin, kun muuttuja on asetettu. Wes tukee tätäkin:

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

Boolean-muuttujat

Voi olla tarpeen varmistaa, että muuttuja on boolean-muodossa, jolloin hyväksytään ”true”, ”false”, ”On”, ”1”, ”Yes”, ”Off”, ”0” ja ”No”. Voit tehdä seuraavasti:

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

Jos ympäristömuuttuja ei ole boolean-muotoinen, saat poikkeuksen:

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

Toisella tavalla voidaan kirjoittaa:

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

Sallitut arvot

Mahdollista on myös määritellä joukko arvoja, joita ympäristömuuttujiesi tulisi olla. Tämä on erityisen hyödyllistä tilanteissa, joissa koodisi todella tukee vain kourallista vaihtoehtoja tai ajureita:

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

Jos ympäristömuuttuja ei kuuluisi tähän sallittujen arvojen listaan, saisit samankaltaisen poikkeuksen:

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

Mahdollista on myös määritellä regex, joka ympäristömuuttujasi pitäisi olla.

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

Voit kommentoida .env-tiedostoa käyttämällä #-merkkiä. Esim.

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

Parsing Without Loading

Joskus haluat vain parsia tiedoston ja ratkaista sisäkkäiset ympäristömuuttujat antamalla meille merkkijonon, ja saada takaisin arkin. Vaikka tämä on jo mahdollista, se on hieman hankalaa, joten olemme tarjonneet suoran tavan tehdä tämä:

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

Tämä on täsmälleen sama kuin:

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

vain sen sijaan, että antaisit hakemiston, josta tiedosto etsitään, olet antanut suoraan tiedoston sisällön.

Käyttöhuomautuksia

Kun uusi kehittäjä kloonaa koodipohjaasi, hän joutuu vielä kerran kopioimaan .env.example-tiedoston manuaalisesti osoitteeseen .env ja täyttämään omat arvonsa (tai hankkimaan arkaluontoiset arvot projektin työtoverilta).

Tietoturva

Jos huomaat tietoturva-aukkoja tässä paketissa, lähettäkää sähköpostia osoitteeseen [email protected] osoitteeseen Graham Campbell. Kaikkiin tietoturva-aukkoihin puututaan viipymättä. Voit tutustua täydelliseen tietoturvapolitiikkaamme täällä.

Lisenssi

PHP dotenv on lisensoitu BSD 3-Clause License -lisenssillä.

For Enterprise

Saatavana osana Tidelift-tilausta

.