Načítá proměnné prostředí z .env do getenv(), $_ENV a $_SERVER automaticky.
Proč .env?
V kódu byste nikdy neměli ukládat citlivé údaje. Ukládáníkonfigurace do prostředí je jedním z principů dvanáctifaktorové aplikace. Vše, co se pravděpodobně změní mezi jednotlivými prostředími nasazení – například pověření pro databázi nebo pověření pro služby třetích stran – by mělo být z kódu extrahováno do proměnných prostředí.
Soubor .env je v podstatě snadný způsob, jak načíst vlastní konfigurační proměnné, které vaše aplikace potřebuje, aniž byste museli upravovat soubory .htaccess nebo virtuální hostitele Apache/nginx. To znamená, že nebudete muset upravovat žádné soubory mimo projekt a všechny proměnné prostředí budou vždy nastaveny bez ohledu na to, jak váš projekt používá – Apache, Nginx, CLI a dokonce i vestavěný webový server PHP. Je to DOST jednodušší než všechny ostatní způsoby nastavení proměnných prostředí,které znáte,a zamilujete si to!
- Žádné úpravy virtuálních hostitelů v Apache nebo Nginx
- Žádné přidávání
php_valuepříznaků do .htaccess souborů - JEDNODUCHÁ přenositelnost a sdílení požadovaných hodnot ENV
- KOMPATIBILNÍ s vestavěným webovým serverem PHP a spouštěčem CLI
PHP dotenv je PHP verze původního Rubydotenv.
Instalace
Instalace je velmi snadná pomocí nástroje Composer:
$ composer require vlucas/phpdotenv
nebo jej přidejte ručně do svého composer.json souboru.
Upgrade
Postupujeme podle sémantického verzování, což znamená, že mezi hlavními verzemi může dojít k rozbití změn. Máme k dispozici průvodce upgradem z V2 na V3, z V3 na V4 a z V4 na V5, které jsou k dispozici zde.
Použití
Soubor .env je obecně držen mimo kontrolu verzí, protože může obsahovat citlivé klíče a hesla API. Je vytvořen samostatný soubor .env.examples definovanými všemi požadovanými proměnnými prostředí s výjimkou citlivých, které si uživatelé buď dodávají pro svá vlastní vývojová prostředí, nebo je sdělují spolupracovníkům projektu jinde. Spolupracovníci projektu pak nezávisle zkopírují soubor .env.example do místního souboru .env a zajistí, aby všechna nastavení byla správná pro jejich místní prostředí, a v případě potřeby vyplní tajné klíče nebo poskytnou vlastní hodnoty. Při tomto použití by měl být soubor .env přidán do souboru .gitignore projektu, aby jej spolupracovníci nikdy neodevzdali. Toto použití zajišťuje, že se v historii správy verzí nikdy neobjeví žádná citlivá hesla nebo klíče API, takže je menší riziko narušení bezpečnosti a výrobní hodnoty nikdy nebudou muset být sdíleny se všemi spolupracovníky projektu.
Přidejte konfiguraci aplikace do souboru .env v kořenovém adresáři projektu. Ujistěte se, že soubor .env je přidán do vašeho .gitignore, aby nebyl zkontrolován v kódu
S3_BUCKET="dotenv"SECRET_KEY="souper_seekret_key"
Nyní vytvořte soubor s názvem .env.example a zkontrolujte jej v projektu. Ten by měl obsahovat proměnné ENV, které potřebujete mít nastavené, ale hodnoty by mělybýt buď prázdné, nebo vyplněné fiktivními daty. Smyslem je dát lidem vědět, jaképroměnné jsou požadovány, ale nedávat jim citlivé výrobní hodnoty.
S3_BUCKET="devbucket"SECRET_KEY="abc123"
V aplikaci pak můžete .env načíst pomocí:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);$dotenv->load();
Pro potlačení výjimky, která je vyhozena, když neexistuje soubor .env, můžete:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);$dotenv->safeLoad();
Případně můžete jako druhý parametr předat název souboru, pokud byste chtěli použít něco jiného než .env:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__, 'myconfig');$dotenv->load();
Všechny definované proměnné jsou nyní dostupné v $_ENV a $_SERVERsuperglobálech.
$s3_bucket = $_ENV;$s3_bucket = $_SERVER;
Putenv a Getenv
Používání getenv() a putenv() se důrazně nedoporučuje vzhledem k tomu, že tyto funkce nejsou bezpečné pro vlákna, nicméně je stále možné instruovatPHP dotenv, aby tyto funkce používal. Namísto volání Dotenv::createImmutable lze volat Dotenv::createUnsafeImmutable, která v zákulisí přidá PutenvAdapter. Vaše proměnné prostředí budou nyní dostupné pomocí metody getenv, stejně jako superglobály:
$s3_bucket = getenv('S3_BUCKET');$s3_bucket = $_ENV;$s3_bucket = $_SERVER;
Vnořování proměnných
Proměnnou prostředí je možné vnořit do jiné, což je užitečné pro omezení opakování.
To se provádí zabalením existující proměnné prostředí do ${…} např.
BASE_DIR="/var/webroot/project-root"CACHE_DIR="${BASE_DIR}/cache"TMP_DIR="${BASE_DIR}/tmp"
Nezměnitelnost a přizpůsobení úložiště
Nezměnitelnost se týká toho, zda je Dotenv povoleno přepisovat existující proměnné prostředí. Pokud chcete, aby Dotenv přepsal existující proměnné prostředí,použijte místo createImmutable createMutable:
$dotenv = Dotenv\Dotenv::createMutable(__DIR__);$dotenv->load();
V pozadí se jedná o pokyn „úložišti“, zda má povolit imutabilitu, nebo ne. Ve výchozím nastavení je úložiště nakonfigurováno tak, aby ve výchozím nastavení umožňovalo přepisování existujícíchhodnot, což má význam, pokud voláme metodu „create“ pomocí RepositoryBuilder pro konstrukci více vlastního úložiště:
$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();
Výše uvedený příklad zapíše načtené hodnoty do $_ENV a putenv, ale přiinterpolaci proměnných prostředí budeme číst pouze z $_ENV. Navíc nikdy nenahradí žádné proměnné, které již byly nastaveny před načtením souboru.
Pomocí jiného příkladu lze také zadat sadu proměnných, které se mají nechat vypsat. To znamená, že budou načteny pouze proměnné v povoleném seznamu:
$repository = Dotenv\Repository\RepositoryBuilder::createWithDefaultAdapters() ->allowList() ->make();$dotenv = Dotenv\Dotenv::create($repository, __DIR__);$dotenv->load();
Vyžadování nastavení proměnných
PHP dotenv má zabudovanou funkci ověřování, včetně vynucení přítomnosti proměnné prostředí. To je užitečné zejména pro informování o výslovně požadovaných proměnných, bez kterých vaše aplikace nebude fungovat.
Můžete použít jediný řetězec:
$dotenv->required('DATABASE_DSN');
Nebo pole řetězců:
$dotenv->required();
Pokud některá z proměnných ENV chybí, Dotenv vyhodí RuntimeExceptionjako je tento:
One or more environment variables failed assertions: DATABASE_DSN is missingPrázdné proměnné
Kromě prostého požadavku na nastavení proměnné můžete také potřebovat zajistit, aby proměnná nebyla prázdná:
$dotenv->required('DATABASE_DSN')->notEmpty();
Pokud je proměnná prostředí prázdná, dostanete výjimku:
One or more environment variables failed assertions: DATABASE_DSN is emptyCeločíselné proměnné
Musíte také zajistit, aby proměnná měla celočíselnou hodnotu. Můžete udělat následující:
$dotenv->required('FOO')->isInteger();
Pokud by proměnná prostředí nebyla celočíselná, dostali byste Výjimku:
One or more environment variables failed assertions: FOO is not an integer.Někdo může chtít vynutit validační pravidla pouze tehdy, když je proměnná nastavena. Wesupodporuje i toto:
$dotenv->ifPresent('FOO')->isInteger();
Logické proměnné
Možná budete potřebovat zajistit, aby proměnná byla ve tvaru logické proměnné, akceptování „true“, „false“, „On“, „1“, „Yes“, „Off“, „0“ a „No“. Můžete provést následující:
$dotenv->required('FOO')->isBoolean();
Pokud proměnná prostředí není boolean, dostanete výjimku:
One or more environment variables failed assertions: FOO is not a boolean.Podobně lze napsat:
$dotenv->ifPresent('FOO')->isBoolean();
Povolené hodnoty
Je také možné definovat sadu hodnot, které by vaše proměnné prostředí měly mít. To je užitečné zejména v situacích, kdy je vaším kódem skutečně podporována jen hrstka možností nebo ovladačů:
$dotenv->required('SESSION_STORE')->allowedValues();
Pokud by proměnná prostředí nebyla v tomto seznamu povolených hodnot, dostali byste podobnou výjimku:
One or more environment variables failed assertions: SESSION_STORE is not an allowed value.Je také možné definovat regex, kterým by měla být vaše proměnná prostředí.
$dotenv->required('FOO')->allowedRegexValues('(]{3})');
Soubor .env můžete okomentovat pomocí znaku #. Například
# this is a commentVAR="value" # commentVAR=value # comment
Parsování bez načítání
Někdy chcete pouze analyzovat soubor a vyřešit vnořené proměnné prostředí tak, že nám zadáte řetězec a zpět vám bude vráceno pole. I když je to již možné, je to trochu krkolomné, proto jsme poskytli přímý způsob, jak to provést:
// Dotenv\Dotenv::parse("FOO=Bar\nBAZ=\"Hello ${FOO}\"");
Je to úplně stejné jako:
Dotenv\Dotenv::createArrayBacked(__DIR__)->load();
jen místo zadání adresáře pro vyhledání souboru jste zadali přímo obsah souboru.
Poznámky k použití
Když nový vývojář naklonuje vaši kódovou základnu, bude muset provést další jednorázový krok, aby ručně zkopíroval soubor .env.example do .env a vyplnil vlastní hodnoty (nebo získal všechny citlivé hodnoty od spolupracovníka projektu).
Bezpečnost
Pokud v tomto balíčku objevíte bezpečnostní chybu, pošlete prosím e-mail Grahamu Campbellovi na adresu [email protected]. Všechny bezpečnostní chyby budou neprodleně vyřešeny. Úplné znění našich bezpečnostních zásad si můžete prohlédnout zde.
Licence
PHP dotenv je licencován pod licencí The BSD 3-Clause License.
Pro podniky
K dispozici v rámci předplatného Tidelift
.