naingaunglwin-dev / dotenv
Simple and lightweight php dotenv library
Requires
- php: ^8.2
Requires (Dev)
- phpunit/phpunit: ^11.5
README
Simple Dotenv Library
About
NAL\Dotenv
is a flexible and lightweight PHP environment loader designed for modern applications.
It supports loading environment variables from .env
and .json
files by default, with the ability to register custom loaders (e.g., YAML, XML) effortlessly.
This package provides:
- Grouped access to related environment keys
- Support for multiple environment files
- Static or instance-based access
- Optional caching for performance
- Convention-based parser resolution
- Seamless integration with custom loaders and parsers
It's ideal for both small-scale projects and larger applications where managing structured and multi-source environment data is essential.
Contributing
- This is an open-source library, and contributions are welcome.
- If you have any suggestions, bug reports, or feature requests, please open an issue or submit a pull request on the project repository.
Requirement
- PHP version 8.2 or newer is required
Installation & Setup
Using Composer
If Composer is not installed, follow the official guide.
- Create a
composer.json
file at your project root directory (if you don't have one):
{ "require": { "naingaunglwin-dev/dotenv": "^2.0" } }
- Run the following command in your terminal from the project's root directory:
composer install
If you already have composer.json
file in your project, just run this command in your terminal,
composer require naingaunglwin-dev/dotenv
Features
✅ Load .env files easily
- Supports standard .env key-value files for environment configuration.
✅ Support for .json config files
- Load structured environment data from JSON files — great for frontend-backend monorepo setups.
✅ Nested key flattening
- Nested JSON keys are automatically flattened into uppercase ENV_STYLE_KEYS.
✅ Environment grouping support
- Automatically organizes keys into groups based on naming conventions like APP_ENV → APP group.
✅ Custom Loader Registry
- Register your own loaders to support formats like YAML, TOML, etc.
✅ Optional override behavior
- Configure whether later files can override previously loaded keys.
✅ Safe loading
- Use
safeLoad()
to prevent exceptions when loading optional or missing files.
✅ Supercharged access methods
- Access environment values using
Env::get('KEY')
or grouped access withEnv::group('APP')
.
✅ Supports multiple files
- Pass an array of files to load them in order — useful for layering config.
Usage
<?php use NAL\Dotenv\Env; $env = Env::create()->load(); // Access values $envs = $env->get('APP_ENV'); // "production" $group = $env->group('DATABASE'); // ['DATABASE_HOST' => '127.0.0.1', ...]
Static Access
You can also use static calls without manually creating an instance:
<?php use NAL\Dotenv\Env; $value = Env::get('APP_ENV'); $group = Env::group('APP');
If no instance was created yet, Env::get() and Env::group() will auto-initialize using default behavior
(.env, no cache)
. If an instance was previously created via Env::create(), the static calls will reuse that instance instead.
Safe Load (No Exceptions)
<?php use NAL\Dotenv\Env; $env = Env::create()->safeLoad(); // Returns ['envs' => [], 'groups' => []] on failure
Load JSON Configuration
<?php use NAL\Dotenv\Env; $env = Env::create(name: 'env.json')->load();
Load Multiple Files
<?php use NAL\Dotenv\Env; Env::create(name: ['.env', '.env.testing'])->load();
Enable Caching
<?php use NAL\Dotenv\Env; Env::create(name: '.env', cache: true)->load(); // Loads once, reuses from memory
Register Custom Loader (e.g., YAML)
<?php use NAL\Dotenv\Loader\LoaderRegistry; $registry = new LoaderRegistry(); $registry->register('yaml', fn ($file, $override, $resolver, $parser) => new YamlLoader( $file, $override, $resolver, $parser ), '\\Namespace\\For\\Parser'); Env::create(name: 'config.yaml', registry: $registry)->load();
Notes for Custom Loader Development
- The registered callback must accept exactly 4 arguments in this order:
($file, $override, $resolver, $parser)
-
Your custom loader must:
-
Implement
NAL\Dotenv\Loader\LoaderInterface
or
-
Extend
NAL\Dotenv\Loader\BaseLoader
for convenient utilities likeresolveFiles()
andsave()
.
-
-
Every custom loader must include a corresponding parser, whose class name:
-
Starts with the capitalized extension name, followed by Parser e.g., for .yaml, the parser must be YamlParser
-
Must implement
NAL\Dotenv\Parser\ParserInterface
-
Parsers are resolved by convention from the namespace
\NAL\Dotenv\Parser\
, or a custom namespace if provided.
Running Tests
- To run the test suite, execute the following command
vendor/bin/phpunit tests/EnvTest.php
- This will run all test cases defined in the EnvTest.php file.