PHPackages enjoys/dotenv - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. enjoys/dotenv ActiveLibrary[Utility & Helpers](/categories/utility) enjoys/dotenv ============= Registers environment variables from a .env file 3.4.0(5mo ago)03.0k↓50%3MITPHPPHP 8.0 - 8.5CI passing Since Sep 11Pushed 5mo ago1 watchersCompare [ Source](https://github.com/Enjoyzz/dotenv)[ Packagist](https://packagist.org/packages/enjoys/dotenv)[ RSS](/packages/enjoys-dotenv/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (6)Dependencies (3)Versions (50)Used By (3) [![build](https://github.com/Enjoyzz/dotenv/actions/workflows/build.yml/badge.svg)](https://github.com/Enjoyzz/dotenv/actions/workflows/build.yml)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/03e2d7acdb8fc8edb67ea2e90f5eaf0689c725f61dd24abac72cec27426faf7a/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f456e6a6f797a7a2f646f74656e762f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/Enjoyzz/dotenv/?branch=master)[![Code Coverage](https://camo.githubusercontent.com/2fdc246a0f8ed0957bd71bb3d47fc7e05a91cc045b859406fafb0ac9c5c9c759/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f456e6a6f797a7a2f646f74656e762f6261646765732f636f7665726167652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/Enjoyzz/dotenv/?branch=master)[![Mutation testing badge](https://camo.githubusercontent.com/ea927c97600a4c478ca487515dbce3fbe1e660777e5e8b988c22304f2eca8f1e/68747470733a2f2f696d672e736869656c64732e696f2f656e64706f696e743f7374796c653d666c61742675726c3d687474707325334125324625324662616467652d6170692e737472796b65722d6d757461746f722e696f2532466769746875622e636f6d253246456e6a6f797a7a253246646f74656e762532466d6173746572)](https://dashboard.stryker-mutator.io/reports/github.com/Enjoyzz/dotenv/master) Парсер .env файлов. =================== [](#парсер-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. (repeat.env. if redefined) $dotenv = new Dotenv(__DIR__.'/.env'); // config available in $_ENV $dotenv->loadEnv(); # config available in $_ENV and getenv() # $dotenv->loadEnv(true); ``` Формат .env файлов ================== [](#формат-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 (приведение типов) [](#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(); ``` [Доступные флаги](#flags) Ниже примеры как будут кастоваться переменные ``` 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" ***Важное примечание*** **НЕ РЕКОМЕНДУЕТСЯ использовать флаг `Dotenv::CAST_TYPE_ENV_VALUE` или `enableCastType()`.** *Хотя автоматическое приведение типов может быть удобным, его использование напрямую через `$_ENV` может быть неочевидным для других разработчиков и усложняет отладку. Значения, приведённые к типам, будут доступны только в рамках текущего PHP-процесса, где была использована эта библиотека.* ***Критически важно понимать**, что при использовании функции `getenv()` (которая часто используется для чтения переменных окружения) всегда возвращаются строковые значения, даже если тип был приведён на уровне парсера и сохранён в `$_ENV`. Это может привести к неожиданным результатам и ошибкам, если код использует смешанный доступ к переменным через `$_ENV` и `getenv()`.* *Также эта функция замедляет парсинг переменных, что особенно заметно на больших объёмах данных.* *Для более предсказуемого и согласованного поведения **рекомендуется использовать функцию** **`env()`**. Она предоставляет те же возможности по приведению типов, но делает это явно в момент обращения к значению. Это делает код читаемым и предотвращает ошибки, связанные с неявным преобразованием типов и различиями в способах хранения переменных (в `$_ENV`, `getenv()` или `$_SERVER`).* ``` // Несогласованное поведение (опасно!): $debugFromEnv = $_ENV['DEBUG']; // bool(true) - если включен CAST_TYPE_ENV_VALUE $debugFromGetenv = getenv('DEBUG'); // string('true') - всегда строка! // Предсказуемое поведение с функцией env() (рекомендуется): $debug1 = env('DEBUG', false); // Всегда bool(false), если переменной нет $debug2 = env('DEBUG', '*true'); // Всегда bool(true), если переменной нет $debug3 = env('DEBUG'); // Значение будет приведено к типу корректно ``` ### Значения переменных по-умолчанию [](#значения-переменных-по-умолчанию) Если переменная не установлена, можно определить значения по-умолчанию. Есть два варианта как это сделать: 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` Функция `env()` =============== [](#функция-env) Удобная функция для работы с переменными окружения с поддержкой преобразования типов, валидации и гибкой обработки значений в callback функции. Базовое использование --------------------- [](#базовое-использование) ``` // Получение значения переменной окружения (вернет localhost если переменная не существует) $dbHost = env('DB_HOST', 'localhost'); // Без значения по умолчанию (вернет null если переменная не существует) $dbPort = env('DB_PORT'); ``` Преобразование типов -------------------- [](#преобразование-типов) ### Автоматическое преобразование типов [](#автоматическое-преобразование-типов) Функция использует ValueTypeCasting::castType() для автоматического преобразования типов. См. [Type Casting (приведение типов)](#type_cast) #### Специальные префиксы для явного указания типов [](#специальные-префиксы-для-явного-указания-типов) ``` // Булевы значения env('DEBUG', '*true'); // → bool(true) env('DEBUG', '*false'); // → bool(false) env('FLAG', '*bool'); // → bool(false) // Числовые значения env('PORT', '*int 8080'); // → int(8080) env('PRICE', '*float 99,99'); // → float(99.99) env('RATE', '*double 3.14'); // → float(3.14) // Строки и null env('NAME', '*string John'); // → string("John") env('OPTIONAL', '*null'); // → null ``` #### Автоматическое преобразование без префиксов [](#автоматическое-преобразование-без-префиксов) ``` // Булевы значения env('DEBUG', 'true'); // → bool(true) env('DEBUG', 'false'); // → bool(false) // Числовые значения env('PORT', '8080'); // → int(8080) env('PRICE', '99.99'); // → float(99.99) env('PRICE', '99,99'); // → float(99.99) - запятые автоматически заменяются // Строки и null env('NAME', 'John Doe'); // → string("John Doe") env('OPTIONAL', 'null'); // → null ``` ### Преобразование значений [](#преобразование-значений) ``` // Простое преобразование типов $port = env('DB_PORT', 3306, fn($v) => (int) $v); $debug = env('APP_DEBUG', false, fn($v) => (bool) $v); // Комплексное преобразование $allowedHosts = env('ALLOWED_HOSTS', 'localhost,127.0.0.1', function($v) { return array_filter(array_map('trim', explode(',', $v))); }); // Использование встроенных функций PHP $env = env('APP_ENV', 'prod', 'strtoupper'); $name = env('APP_NAME', 'My App', 'trim'); ``` ### Валидация значений [](#валидация-значений) ``` // Преобразование + валидация в одном callback $port = env('PORT', 8080, function($value) { $value = (int) $value; if ($value < 1 || $value > 65535) { throw new InvalidArgumentException("Port must be between 1 and 65535"); } return $value; }); // Массив хостов с валидацией $allowedHosts = env('ALLOWED_HOSTS', 'localhost', function($value) { $hosts = array_filter(array_map('trim', explode(',', $value))); if (empty($hosts)) { throw new InvalidArgumentException("At least one host required"); } return $hosts; }); ``` ### Получение сырых значений (RAW) [](#получение-сырых-значений-raw) ``` // Используйте callback, который возвращает значение как есть $rawValue = env('SOME_VAR', null, fn($v) => $v); ``` Практические примеры -------------------- [](#практические-примеры) Конфигурация приложения: ``` return [ 'debug' => env('APP_DEBUG', false, fn($v) => (bool) $v), 'env' => env('APP_ENV', 'production', 'strtolower'), 'name' => env('APP_NAME', 'My App', 'trim'), 'database' => [ 'host' => env('DB_HOST', 'localhost'), 'port' => env('DB_PORT', 3306, function($v) { $port = (int) $v; if ($port env('DB_NAME', 'app'), 'user' => env('DB_USER', 'root'), 'pass' => env('DB_PASS', '', function($v) { if (empty($v)) {throw new InvalidArgumentException("DB password is required");} return $v; }), ], 'api' => [ 'key' => env('API_KEY', null, function($v, $key) { if (empty($v)) {throw new InvalidArgumentException("$key is required");} return trim($v); }), 'timeout' => env('API_TIMEOUT', 30.0, 'floatval'), ] ]; ``` Особенности работы ------------------ [](#особенности-работы) **Приоритеты получения значений** Функция проверяет переменные в следующем порядке: 1. getenv() - системные переменные окружения 2. $\_ENV - массив переменных окружения PHP 3. Значение по умолчанию ``` // Если установлено и в getenv() и в $_ENV - используется getenv() putenv('TEST_VAR=system_value'); $_ENV['TEST_VAR'] = 'env_value'; env('TEST_VAR'); // → "system_value" ``` ### Health Score 50 — FairBetter than 96% of packages Maintenance72 Regular maintenance activity Popularity21 Limited adoption so far Community12 Small or concentrated contributor base Maturity81 Battle-tested with a long release history Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~33 days Recently: every ~21 days Total 48 Last Release 159d ago Major Versions 1.0.8 → 2.0.02021-09-25 1.0.9 → 2.0.22022-02-12 2.x-dev → 3.0.0-alpha12022-09-02 3.x-dev → 4.x-dev2025-12-10 PHP version history (6 changes)1.0.0PHP >=7.4 1.0.7PHP >=7.3 2.0.0PHP >=8.0 3.0.6PHP ^8.0 3.4.0PHP 8.0 - 8.5 4.x-devPHP 8.3 - 8.5 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/25447823?v=4)[enjoys](/maintainers/enjoys)[@enjoys](https://github.com/enjoys) --- Top Contributors [![Enjoyzz](https://avatars.githubusercontent.com/u/1448659?v=4)](https://github.com/Enjoyzz "Enjoyzz (198 commits)") --- Tags dotenvenvironmentparse-envphpenvironmentenvdotenv ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/enjoys-dotenv/health.svg) ``` [![Health](https://phpackages.com/badges/enjoys-dotenv/health.svg)](https://phpackages.com/packages/enjoys-dotenv) ``` ### Alternatives [vlucas/phpdotenv Loads environment variables from `.env` to `getenv()`, `$\_ENV` and `$\_SERVER` automagically. 13.5k602.4M5.4k](/packages/vlucas-phpdotenv)[symfony/dotenv Registers environment variables from a .env file 3.8k226.7M2.3k](/packages/symfony-dotenv)[diarmuidie/envpopulate Tool to interactively populate a `.env` file based on an `.env.example` file whenever Composer installs or updates. 1892.0k](/packages/diarmuidie-envpopulate)[zepgram/magento-dotenv Simple autoloader to integrate the Symfony Dotenv component into Magento2 1371.3k](/packages/zepgram-magento-dotenv)[nystudio107/dotenvy Speed up your production sites by ditching .env for key/value variable pairs as Apache, Nginx, and shell equivalents. 326.9k](/packages/nystudio107-dotenvy) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)