EnvSystem class

The default environment variable manager used by Khadem.

The EnvSystem provides a comprehensive environment variable management system that supports loading from .env files, process environment variables, type casting, and variable substitution. It's designed to be flexible and easy to use in various application contexts.

Features

File Loading: Automatically loads .env files with support for comments, export statements, and various quote styles
Type Casting: Converts string values to bool, int, double, and List types
Variable Substitution: Supports $VAR and ${VAR} syntax for referencing other environment variables
Process Environment: Can optionally load system environment variables
Validation: Provides methods to validate required environment variables

Usage

// Create a new environment system
final env = EnvSystem();

// Load additional env files
env.loadFromFile('.env.local');

// Get values with type conversion
final port = env.getInt('PORT', defaultValue: 3000);
final debug = env.getBool('DEBUG', defaultValue: false);
final hosts = env.getList('ALLOWED_HOSTS', separator: ';');

// Set values programmatically
env.set('API_KEY', 'secret-key');

// Validate required variables
final missing = env.validateRequired(['DATABASE_URL', 'API_KEY']);
if (missing.isNotEmpty) {
  throw Exception('Missing required env vars: $missing');
}

.env File Format

The system supports standard .env file syntax:

# Comments are supported
APP_NAME=MyApp
APP_VERSION=1.0.0
DEBUG=true
PORT=3000

# Quotes are optional but recommended for complex values
DATABASE_URL="postgresql://user:pass@localhost:5432/db"

# Export statements are supported
export REDIS_URL=redis://localhost:6379

# Variable substitution
API_BASE_URL=http://localhost:$PORT
FULL_NAME="${APP_NAME} v${APP_VERSION}"

Implemented types

EnvInterface

Constructors

EnvSystem({bool useProcessEnv = true}): Creates a new environment system.

Properties

hashCode → int: The hash code for this object.
no setterinherited
loadedFiles → List<String>: Returns a list of all loaded environment files.
no setteroverride
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

all() → Map<String, String>: Returns a copy of all environment variables.
override
clear() → void: Clears all environment variables and loaded files.
override
get(String key) → String?: Retrieves the value of an environment variable.
override
getBool(String key, {bool defaultValue = false}) → bool: Retrieves a boolean value from an environment variable.
override
getDouble(String key, {double defaultValue = 0.0}) → double: Retrieves a double value from an environment variable.
override
getInt(String key, {int defaultValue = 0}) → int: Retrieves an integer value from an environment variable.
override
getList(String key, {String separator = ',', List<String> defaultValue = const []}) → List<String>: Retrieves a list of strings from an environment variable.
override
getOrDefault(String key, String defaultValue) → String: Retrieves the value of an environment variable with a default fallback.
override
getOrFail(String key) → String: Returns the value of the key or throws an exception if not found.
override
has(String key) → bool: Checks if an environment variable is set.
override
loadFromFile(String path) → void: Loads environment variables from a file.
override
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
set(String key, String value) → void: Sets the value of an environment variable.
override
toString() → String: A string representation of this object.
inherited
validateRequired(List<String> requiredKeys) → List<String>: Validates that all required environment variables are set.
override

Operators

operator ==(Object other) → bool: The equality operator.
inherited