Wczytuje zmienne środowiskowe z .env do getenv(), $_ENV i $_SERVER automatycznie.
Dlaczego .env?
Nigdy nie powinieneś przechowywać wrażliwych danych uwierzytelniających w swoim kodzie. Przechowywanie konfiguracji w środowisku jest jednym z założeń aplikacji opartej na dwunastu czynnikach. Wszystko, co może się zmienić pomiędzy środowiskami wdrażania – takie jak dane uwierzytelniające bazy danych lub dane uwierzytelniające dla usług innych firm – powinno zostać wyodrębnione z kodu do zmiennych środowiskowych.
Podstawowo, plik .env jest łatwym sposobem na załadowanie niestandardowych zmiennych konfiguracyjnych, których potrzebuje Twoja aplikacja bez konieczności modyfikowania plików .htaccess lub wirtualnych hostów Apache/nginx. Oznacza to, że nie będziesz musiał edytować żadnych plików spoza projektu, a wszystkie zmienne środowiskowe będą zawsze ustawione, niezależnie od tego, w jaki sposób uruchomisz swój projekt – Apache, Nginx, CLI, a nawet wbudowany w PHP serwer WWW. Jest to o wiele łatwiejsze niż wszystkie inne znane ci sposoby ustawiania zmiennych środowiskowych i pokochasz to!
- NIE edytuj wirtualnych hostów w Apache lub Nginx
- NIE dodawaj flag
php_valuedo plików .htaccess - Łatwe przenoszenie i współdzielenie wymaganych wartości ENV
- KOMPATYBILNE z wbudowanym w PHP serwerem WWW i CLI runner
PHP dotenv jest PHP-ową wersją oryginalnego Rubydotenv.
Instalacja
Instalacja jest super łatwa przez Composer:
$ composer require vlucas/phpdotenv
lub dodaj ją ręcznie do swojego pliku composer.json.
Aktualizacja
Postępujemy zgodnie z semantycznym wersjonowaniem, co oznacza, że między głównymi wydaniami mogą wystąpić zmiany. Mamy przewodniki aktualizacji dostępne dla V2 do V3, V3 do V4 i V4 do V5 dostępne tutaj.
Użycie
Plik .env jest generalnie trzymany poza kontrolą wersji, ponieważ może zawierać wrażliwe klucze API i hasła. Oddzielny plik .env.example jest tworzony ze zdefiniowanymi wszystkimi wymaganymi zmiennymi środowiskowymi z wyjątkiem tych wrażliwych, które są albo dostarczane przez użytkowników dla ich własnych środowisk programistycznych, albo przekazywane w innym miejscu współpracownikom projektu. Współpracownicy projektu następnie niezależnie kopiują plik .env.example do lokalnego .env i upewniają się, że wszystkie ustawienia są poprawne dla ich lokalnego środowiska, wypełniając tajne klucze lub podając własne wartości w razie potrzeby. W tym przypadku plik .env powinien być dodany do pliku .gitignore projektu, aby nigdy nie został popełniony przez współpracowników. Ten sposób użycia zapewnia, że żadne poufne hasła lub klucze API nigdy nie znajdą się w historii kontroli wersji, więc istnieje mniejsze ryzyko naruszenia bezpieczeństwa, a wartości produkcyjne nigdy nie będą musiały być dzielone ze wszystkimi współpracownikami projektu.
Dodaj konfigurację aplikacji do pliku .env w korzeniu projektu. Upewnij się, że plik .env jest dodany do twojego .gitignore, więc nie jest sprawdzany w kodzie
S3_BUCKET="dotenv"SECRET_KEY="souper_seekret_key"
Teraz utwórz plik o nazwie .env.example i sprawdź go w projekcie. Powinien on zawierać zmienne ENV, które musisz mieć ustawione, ale wartości powinny być albo puste, albo wypełnione fikcyjnymi danymi. Chodzi o to, aby ludzie wiedzieli, jakie zmienne są wymagane, ale nie podawać im wrażliwych wartości produkcyjnych.
S3_BUCKET="devbucket"SECRET_KEY="abc123"
Możesz wtedy załadować .env w swojej aplikacji za pomocą:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);$dotenv->load();
Aby stłumić wyjątek, który jest rzucany, gdy nie ma pliku .env, możesz:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);$dotenv->safeLoad();
Opcjonalnie możesz przekazać nazwę pliku jako drugi parametr, jeśli chciałbyś użyć czegoś innego niż .env:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__, 'myconfig');$dotenv->load();
Wszystkie zdefiniowane zmienne są teraz dostępne w $_ENV i $_SERVERsuperglobalach.
$s3_bucket = $_ENV;$s3_bucket = $_SERVER;
Putenv i Getenv
Używanie getenv() i putenv() jest zdecydowanie odradzane ze względu na fakt, że funkcje te nie są bezpieczne dla wątków, jednak nadal można poinstruować PHP dotenv, aby używał tych funkcji. Zamiast wywoływaćDotenv::createImmutable, można wywołać Dotenv::createUnsafeImmutable, co spowoduje dodanie PutenvAdapter za kulisami. Twoje zmienne środowiskowe będą teraz dostępne przy użyciu metody getenv, a także superglobali:
$s3_bucket = getenv('S3_BUCKET');$s3_bucket = $_ENV;$s3_bucket = $_SERVER;
Zagnieżdżanie zmiennych
Możliwe jest zagnieżdżanie zmiennej środowiskowej wewnątrz innej, przydatne do zmniejszenia liczby powtórzeń.
Do tego służy zawijanie istniejącej zmiennej środowiskowej w ${…} np.
BASE_DIR="/var/webroot/project-root"CACHE_DIR="${BASE_DIR}/cache"TMP_DIR="${BASE_DIR}/tmp"
Niezmienność i dostosowywanie repozytorium
Niezmienność odnosi się do tego, czy Dotenv może nadpisywać istniejące zmienne środowiskowe. Jeśli chcesz, aby Dotenv nadpisywał istniejące zmienne środowiskowe, użyj createMutable zamiast createImmutable:
$dotenv = Dotenv\Dotenv::createMutable(__DIR__);$dotenv->load();
Za kulisami, jest to instrukcja dla „repozytorium”, aby pozwolić na niezmienność lub nie. Domyślnie, repozytorium jest skonfigurowane tak, aby domyślnie zezwalało na nadpisywanie istniejących wartości, co jest istotne, jeśli ktoś wywołuje metodę „create” używając RepositoryBuilder do skonstruowania bardziej niestandardowego repozytorium:
$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();
Powyższy przykład zapisze załadowane wartości do $_ENV i putenv, ale podczas interpolacji zmiennych środowiskowych, będziemy czytać tylko z $_ENV. Co więcej, nigdy nie zastąpi żadnych zmiennych ustawionych przed załadowaniem pliku.
Przy pomocy innego przykładu, można również określić zestaw zmiennych, które mają być wylistowane. Oznacza to, że tylko zmienne z listy dozwolonych zostaną załadowane:
$repository = Dotenv\Repository\RepositoryBuilder::createWithDefaultAdapters() ->allowList() ->make();$dotenv = Dotenv\Dotenv::create($repository, __DIR__);$dotenv->load();
Wymaganie ustawienia zmiennych
PHP dotenv ma wbudowaną funkcjonalność sprawdzania poprawności, włączając w to wymuszanie obecności zmiennej środowiskowej. Jest to szczególnie przydatne, aby dać ludziom znać o wszelkich jawnie wymaganych zmiennych, bez których twoja aplikacja nie będzie działać.
Możesz użyć pojedynczego łańcucha:
$dotenv->required('DATABASE_DSN');
Albo tablicy łańcuchów:
$dotenv->required();
Jeśli brakuje jakichkolwiek zmiennych ENV, Dotenv wyrzuci RuntimeException jak poniżej:
One or more environment variables failed assertions: DATABASE_DSN is missingPuste zmienne
Poza zwykłym wymaganiem, aby zmienna była ustawiona, możesz również potrzebować upewnić się, że zmienna nie jest pusta:
$dotenv->required('DATABASE_DSN')->notEmpty();
Jeśli zmienna środowiskowa jest pusta, otrzymasz wyjątek:
One or more environment variables failed assertions: DATABASE_DSN is emptyInteger Variables
Możesz również potrzebować upewnić się, że zmienna ma wartość całkowitą. Możesz wykonać następujące czynności:
$dotenv->required('FOO')->isInteger();
Jeśli zmienna środowiskowa nie jest liczbą całkowitą, otrzymasz wyjątek:
One or more environment variables failed assertions: FOO is not an integer.Możesz chcieć egzekwować reguły sprawdzania poprawności tylko wtedy, gdy zmienna jest ustawiona. Wesupport this too:
$dotenv->ifPresent('FOO')->isInteger();
Zmienne boolean
Możesz potrzebować zapewnić, że zmienna jest w formie boolean, akceptując „true”, „false”, „On”, „1”, „Yes”, „Off”, „0” i „No”. Możesz wykonać następujące czynności:
$dotenv->required('FOO')->isBoolean();
Jeśli zmienna środowiskowa nie jest booleanem, otrzymasz wyjątek:
One or more environment variables failed assertions: FOO is not a boolean.Podobnie można napisać:
$dotenv->ifPresent('FOO')->isBoolean();
Dozwolone wartości
Możliwe jest również zdefiniowanie zestawu wartości, jakie powinny mieć zmienne środowiskowe. Jest to szczególnie przydatne w sytuacjach, gdy tylko garstka opcji lub sterowników jest faktycznie obsługiwana przez twój kod:
$dotenv->required('SESSION_STORE')->allowedValues();
Jeśli zmienna środowiskowa nie znajdowałaby się na tej liście dozwolonych wartości, otrzymałbyś podobny wyjątek:
One or more environment variables failed assertions: SESSION_STORE is not an allowed value.Możliwe jest również zdefiniowanie regex, którym powinna być twoja zmienna środowiskowa.
$dotenv->required('FOO')->allowedRegexValues('(]{3})');
Możesz skomentować swój plik .env używając znaku #. Np.
# this is a commentVAR="value" # commentVAR=value # comment
Parsowanie bez ładowania
Czasami chcesz po prostu przetworzyć plik i rozwiązać zagnieżdżone zmienne środowiskowe, podając nam ciąg znaków, a następnie otrzymać tablicę z powrotem. Chociaż jest to już możliwe, jest to trochę kłopotliwe, więc zapewniliśmy bezpośredni sposób na zrobienie tego:
// Dotenv\Dotenv::parse("FOO=Bar\nBAZ=\"Hello ${FOO}\"");
Jest to dokładnie to samo co:
Dotenv\Dotenv::createArrayBacked(__DIR__)->load();
tylko, zamiast podawać katalog do znalezienia pliku, podałeś bezpośrednio zawartość pliku.
Uwagi dotyczące użycia
Kiedy nowy programista sklonuje twoją bazę kodu, będzie musiał wykonać dodatkowy, jednorazowy krok, aby ręcznie skopiować plik .env.example do .env i wypełnić go własnymi wartościami (lub uzyskać wrażliwe wartości od współpracownika projektu).
Bezpieczeństwo
Jeśli odkryjesz lukę bezpieczeństwa w tym pakiecie, wyślij wiadomość e-mail do Grahama Campbella na adres [email protected]. Wszystkie luki w zabezpieczeniach zostaną niezwłocznie usunięte. Możesz przejrzeć naszą pełną politykę bezpieczeństwa tutaj.
Licencja
PHP dotenv jest objęty licencją BSD 3-Clause License.
Dla przedsiębiorstw
Dostępny jako część subskrypcji Tidelift
.