enjoys/dotenv

Registers environment variables from a .env file

3.1.0 2025-04-13 19:56 UTC

Requires

• php: ^8.0

Requires (Dev)

• infection/infection: ^0.26 | ^0.29
• phpunit/phpunit: ^9.6
• symfony/var-dumper: ^5.4 | ^6.0 | ^7.0
• vimeo/psalm: ^5.15 | ^6.4

MIT

• environment
• env
• dotenv

README

Парсер .env файлов.

Загружаются .env.dist, .env и остальные файлы в зависимости от APP_ENV. Например, если APP_ENV=test, будет попытка загрузить .env.test

Приоритет конфигурационных файлов

• сначала загружается dist файл, но у него приоритет самый низкий.
• потом загружается основной файл (.env), все параметры которые в нём определены - перезапишут dist
• и последний файл - это файл окружения, если он существует. все параметры в нем будут иметь наивысший приоритет, и они перезапишут предыдущие значения. Этот файл не обязателен.
• переменные окружения установленные системно, например через export и т.п. имеют наивысший приоритет, так как они не перезаписываются

Установка

composer require enjoys/dotenv

Использование

use Enjoys\Dotenv\Dotenv;
 
# loaded line __DIR__.'/.env.dist -> __DIR__.'/.env' -> __DIR__.'/.env.<APP_ENV> (repeat.env.<APP_ENV> if redefined) 
$dotenv = new Dotenv(__DIR__.'/.env'); 
// config available in $_ENV
$dotenv->loadEnv(); 

# config available in $_ENV and getenv()
# $dotenv->loadEnv(true); 

Формат .env файлов

VAR1 = value # можно использовать пробелы вокруг знака `=`
VAR2=value2
VAR3="this is value #3"
VAR4=value 4 #return `value 4
VAR5=${VAR4}2 # variable, return `value 42`
VAR6="it\'s a beautiful life"
VAR7 # if set Parser::AUTO_CAST_VALUE_TYPE return `null`, else empty string
VAR8= #return empty string
VAR9=${NOT_DEFINED_VAR:-value} # VAR9='value', but NOT_DEFINED_VAR - not set
VAR10=${NOT_DEFINED_VAR:=value} # VAR10='value' and  NOT_DEFINED_VAR='value'
VAR10=${NOT_DEFINED_VAR:?} # throw Exception

Дополнительные возможности

Type Casting (приведение типов)

Все значения в .env файле являются строками (string), но иногда было бы хорошо привести значение к соответствующему типу. Это возможно, установив свойство $castType в true с помощью метода enableCastType().

use Enjoys\Dotenv\Dotenv;
$dotenv = new  Dotenv(__DIR__.'/.env');
$dotenv->enableCastType();
$dotenv->loadEnv();

...или с помощью флага Dotenv::CAST_TYPE_ENV_VALUE

use \Enjoys\Dotenv\Dotenv;
$dotenv = new Dotenv(__DIR__.'/.env', flags: Dotenv::CAST_TYPE_ENV_VALUE);
$dotenv->loadEnv();

Доступные флаги

Ниже примеры как будут кастоваться переменные

VAR = *true  #bool(true)
VAR = true  #bool(true)
VAR = *false  #bool(false)
VAR = false  #bool(false)
VAR = *bool somethig  #bool(true)
VAR = *bool  #bool(false)
VAR = *int 42  #int(42)
VAR = "*int 42"  #string
VAR = 42  #int(42)
VAR = '42'  #string
VAR = 3.14  #float(3.14)
VAR = 3,14  #float(3.14)
VAR = *float 3,14  #float(3.14)
VAR = *double 3.14  #float(3.14)
VAR = "3.14"  #string
#и т.д.

• *bool - return bool(true) or bool(false)
• *true - return bool(true)
• *false - return bool(false)
• *null - return NULL
• *int *int 42 return int(42)
• *int8
• *int16
• *float or *double *float 3,14 return float(3.14), запятые автоматически заменяются на точки
• *string - *string *int return string(4) "*int"

Внимание Type Casting будет работать только при использовании этой библиотеки, при парсинге файла другими библиотеками или системой значения скорее всего приведены к типам не будут.

Значения переменных по-умолчанию

Если переменная не установлена, можно определить значения по-умолчанию. Есть два варианта как это сделать:

1. ${VAR:-default} - при этом варианте, если переменная не будет установлена, вернется значение после знака :-, переменная при этом также останется не установленной, в противном случае будет возвращено значение переменной.
2. ${VAR:=default} - при этом варианте, если переменная не будет установлена, вернется значение после знака := и установить переменную с этим значением, в противном случае будет возвращено значение переменной.

Внимание! Если переменная не установлена, и не переданы значения по-умолчанию, будет возвращена пустая строка.

Чтобы вызвать ошибку при таком сценарии, можно указать после наименования переменной :?, или :?message. И в случае если переменная не была установлена, будет выброшено исключение \Enjoys\Dotenv\Exception\InvalidArgumentException

Например:

VAR1=${NOT_DEFINED_VAR:?extended error message} #with error message
VAR2=${NOT_DEFINED_VAR:?} #or just with empty error message

Доступные флаги

• CLEAR_MEMORY_AFTER_LOAD_ENV - очищает память после установки всех значений в $_ENV, $_SERVER или putenv()
• CAST_TYPE_ENV_VALUE - приводит к типу на основе содержимого (string|bool|int|float|null)
• POPULATE_PUTENV - будут доступны установленные значения помимо $_ENV также из getenv()
• POPULATE_SERVER - будут доступны установленные значения помимо $_ENV также из $_SERVER

Флаги можно комбинировать через |, например Dotenv::CAST_TYPE_ENV_VALUE|Dotenv::POPULATE_PUTENV