A környezetváltozók automatikus betöltése a .env-ből a getenv(), $_ENV és $_SERVER környezetváltozókba.
Miért .env?
Soha ne tároljon érzékeny hitelesítő adatokat a kódjában. A konfiguráció tárolása a környezetben a tizenkétfaktoros alkalmazások egyik alapelve. Bármi, ami valószínűleg változik a telepítési környezetek között – mint például az adatbázis- vagy a harmadik féltől származó szolgáltatások hitelesítő adatai – a kódból a környezeti változókba kell kivenni.
Az .env fájl alapvetően egy egyszerű módja annak, hogy az alkalmazásnak szüksége van az egyéni konfigurációs változók betöltésére anélkül, hogy a .htaccess fájlokat vagy az APache/nginx virtuális hosztokat módosítania kellene. Ez azt jelenti, hogy nem kell a projekten kívül semmilyen fájlt szerkesztenie, és az összes környezeti változó mindig be lesz állítva, függetlenül attól, hogy hogyan indítja el a projektet – Apache, Nginx, CLI, vagy akár a PHP beépített webszerverét. Ez sokkal egyszerűbb, mint a környezeti változók beállításának minden más ismert módja,és imádni fogod!
- NEM kell virtuális hosztokat szerkeszteni az Apache-ban vagy a Nginx-ben
- NEM kell
php_valuezászlókat hozzáadni a .htaccess fájlok - Egyszerű hordozhatóság és a szükséges ENV értékek megosztása
- KOMPATIBILIS a PHP beépített webszerverével és CLI futójával
A PHP dotenv az eredeti Rubydotenv PHP változata.
Telepítés
A telepítés szuperegyszerű a Composer segítségével:
$ composer require vlucas/phpdotenv
vagy adjuk hozzá kézzel a composer.json fájlunkhoz.
Frissítés
Semantikus verziókezelést követünk, ami azt jelenti, hogy a nagyobb kiadások között törésváltozások előfordulhatnak. A frissítési útmutatók a V2-ről V3-ra, a V3-ról V4-re és a V4-ről V5-re itt érhetők el.
Használat
A .env fájlt általában a verziókezelésen kívül tartjuk, mivel érzékeny API kulcsokat és jelszavakat tartalmazhat. Egy külön .env.example fájl jön létre, amelyben az összes szükséges környezeti változó definiálva van, kivéve az érzékenyeket, amelyeket vagy a felhasználók adnak meg a saját fejlesztőkörnyezetükhöz, vagy máshol közlik a projekt munkatársaival. A projekt munkatársai ezután önállóan másolják a .env.example fájlt egy helyi .env fájlba, és biztosítják, hogy minden beállítás megfeleljen a helyi környezetüknek, kitöltve a titkos kulcsokat vagy megadva saját értékeiket, ha szükséges. Ebben a felhasználási módban a .envfájlt hozzá kell adni a projekt .gitignore fájljához, hogy a munkatársak soha ne tudják átadni. Ez a használat biztosítja, hogy soha nem lesznek érzékeny jelszavak vagy API-kulcsok a verziókezelési előzményekben, így kisebb a biztonság megsértésének kockázata, és a gyártási értékeket soha nem kell megosztani a projekt összes munkatársával.
Adja hozzá az alkalmazás konfigurációját egy .env fájlhoz a projekt gyökerében. Győződjön meg róla, hogy a .env fájl hozzá van adva a .gitignore-hoz, hogy ne legyen ellenőrizve a kódban
S3_BUCKET="dotenv"SECRET_KEY="souper_seekret_key"
Ezután hozzon létre egy .env.example nevű fájlt, és ellenőrizze ezt a projektben. Ennek tartalmaznia kell az ENV változókat, amelyeket be kell állítani, de az értékeknek vagy üresnek kell lenniük, vagy dummy adatokkal kell kitölteniük. Az ötlet az, hogy tudassuk az emberekkel, hogy milyen változókra van szükség, de ne adjuk meg nekik az érzékeny termelési értékeket.
S3_BUCKET="devbucket"SECRET_KEY="abc123"
Az .env-t ezután betöltheted az alkalmazásodba:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);$dotenv->load();
Az .env fájl hiánya esetén dobott kivétel elnyomása érdekében:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);$dotenv->safeLoad();
Egy fájlnevet is átadhatsz második paraméterként, ha a .env helyett mást szeretnél használni:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__, 'myconfig');$dotenv->load();
Az összes definiált változó elérhetővé vált a $_ENV és $_SERVERsuper-globálokban.
$s3_bucket = $_ENV;$s3_bucket = $_SERVER;
Putenv és Getenv
A getenv() és putenv() használata erősen nem ajánlott, mivel ezek a függvények nem szálbiztosak, azonban továbbra is lehet utasítani aPHP dotenv-t, hogy használja ezeket a függvényeket. A Dotenv::createImmutable hívása helyett meg lehet hívni a Dotenv::createUnsafeImmutable-et, amely a színfalak mögött hozzáadja a PutenvAdapter-ot. A környezeti változók mostantól elérhetőek lesznek a getenv módszerrel, valamint a szuper-globálokkal:
$s3_bucket = getenv('S3_BUCKET');$s3_bucket = $_ENV;$s3_bucket = $_SERVER;
Változók fészkelése
Egy környezeti változót egy másikba fészkelhetünk, ami hasznos az ismétlések csökkentésére.
Ez úgy történik, hogy egy meglévő környezeti változót ${…}-be csomagolunk, pl.
BASE_DIR="/var/webroot/project-root"CACHE_DIR="${BASE_DIR}/cache"TMP_DIR="${BASE_DIR}/tmp"
Immutability and Repository Customization
Az immutabilitás arra vonatkozik, hogy a Dotenv felülírhatja-e a meglévő környezeti változókat. Ha azt szeretné, hogy a Dotenv felülírja a meglévő környezeti változókat,használja a createImmutable helyett a createMutable-t:
$dotenv = Dotenv\Dotenv::createMutable(__DIR__);$dotenv->load();
A színfalak mögött ez utasítja a “tárolót”, hogy engedélyezze az immutabilitástvagy sem. Alapértelmezés szerint a tároló úgy van beállítva, hogy alapértelmezésben engedélyezi a meglévőértékek felülírását, ami akkor lényeges, ha valaki a “create” metódust hívja meg a RepositoryBuilder használatával, hogy egy testreszabottabb tárolót építsen:
$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();
A fenti példa betöltött értékeket ír a $_ENV és putenv helyekre, de a környezeti változók interpolálásakor csak a $_ENV helyről fogunk olvasni. Ráadásul soha nem fogja helyettesíteni a fájl betöltése előtt már beállított változókat.
Egy másik példával megadhatunk egy változóhalmazt is, amelyet engedélyezni kell a felsorolásban. Ez azt jelenti, hogy csak az engedélyezett listában szereplő változók töltődnek be:
$repository = Dotenv\Repository\RepositoryBuilder::createWithDefaultAdapters() ->allowList() ->make();$dotenv = Dotenv\Dotenv::create($repository, __DIR__);$dotenv->load();
Változók beállításának megkövetelése
APHP dotenv beépített érvényesítési funkciókkal rendelkezik, többek között egy környezeti változó jelenlétének kikényszerítésére. Ez különösen hasznos, hogy tudassa az emberekkel a kifejezetten szükséges változókat, amelyek nélkül az alkalmazásod nem fog működni.
Egyetlen karakterláncot használhat:
$dotenv->required('DATABASE_DSN');
Vagy karakterláncok tömbjét:
$dotenv->required();
Ha bármelyik ENV vars hiányzik, a Dotenv egy RuntimeException hasonlót fog dobni:
One or more environment variables failed assertions: DATABASE_DSN is missingÜres változók
Túl azon, hogy egy változót egyszerűen be kell állítani, szükség lehet arra is, hogy a változó ne legyen üres:
$dotenv->required('DATABASE_DSN')->notEmpty();
Ha a környezeti változó üres, akkor Exceptiont kapunk:
One or more environment variables failed assertions: DATABASE_DSN is emptyInteger Variables
Azt is biztosítanunk kell, hogy a változó egész értékű legyen. A következőket teheti:
$dotenv->required('FOO')->isInteger();
Ha a környezeti változó nem egész szám, akkor Exceptiont kap:
One or more environment variables failed assertions: FOO is not an integer.Egy változó beállításakor csak az érvényesítési szabályokat akarhatjuk érvényesíteni. A Wes ezt is támogatja:
$dotenv->ifPresent('FOO')->isInteger();
Boolean Variables
Szükség lehet arra, hogy egy változó boolean formában legyen, elfogadva a “true”, “false”, “On”, “1”, “Yes”, “Off”, “0” és “No” értékeket. A következőket teheti:
$dotenv->required('FOO')->isBoolean();
Ha a környezeti változó nem boolean, akkor Exceptiont kap:
One or more environment variables failed assertions: FOO is not a boolean.Hasonlóképpen írhatja:
Allowed Values
A környezeti változók értékkészletének meghatározása is lehetséges. Ez különösen hasznos olyan helyzetekben, amikor csak egy maroknyiopciót vagy meghajtót támogat a kódod:
$dotenv->required('SESSION_STORE')->allowedValues();
Ha a környezeti változó nem szerepel a megengedett értékek listáján, akkor hasonló Exceptiont kapsz:
One or more environment variables failed assertions: SESSION_STORE is not an allowed value.Megadható egy regex is, amit a környezeti változónak kell lennie.
$dotenv->required('FOO')->allowedRegexValues('(]{3})');
A .env fájlodat a # karakterrel kommentálhatod. Pl.
# this is a commentVAR="value" # commentVAR=value # comment
Parsing Without Loading
Néha csak elemezni akarod a fájlt és feloldani a beágyazott környezeti változókat, megadva nekünk egy stringet, és egy tömböt kapsz vissza. Bár ez már lehetséges, de egy kicsit körülményes, ezért megadtuk ennek közvetlen módját:
// Dotenv\Dotenv::parse("FOO=Bar\nBAZ=\"Hello ${FOO}\"");
Ez pontosan ugyanaz, mint:
Dotenv\Dotenv::createArrayBacked(__DIR__)->load();
csak ahelyett, hogy megadnánk a könyvtárat a fájl kereséséhez, közvetlenül a fájl tartalmát adtuk meg.
Használati megjegyzések
Amikor egy új fejlesztő klónozza a kódbázisát, egy további, egyszeri lépést kell tennie, hogy manuálisan átmásolja a .env.example fájlt a .env-be, és kitöltse a saját értékeit (vagy megkapja az érzékeny értékeket egy projekt munkatársától).
Biztonság
Ha biztonsági rést fedez fel ebben a csomagban, kérjük, küldjön egy e-mailt Graham Campbellnek a [email protected] címre. Minden biztonsági rést azonnal orvosolni fogunk. A teljes biztonsági szabályzatunkat itt tekintheti meg.
Licenc
PHP dotenv a BSD 3-Clause License alatt áll.
For Enterprise
A Tidelift Subscription
részeként érhető el.