env

Environment Module

The environment module provides utilities for working with environment variables, including normalized access, type-safe retrieval, and .env file loading.

Features

• Normalized Environment Access: Consistent naming conventions for environment variables
• Type-Safe Retrieval: Safe conversion to common types (bool, int, float)
• .env File Support: Automatic loading of .env files with godotenv
• Environment Expansion: Variable substitution with envsubst
• Flexible Lookup: Multiple fallback mechanisms for variable resolution

Installation

go get github.com/pubgo/funk/v2/env

Quick Start

Basic Environment Access

import "github.com/pubgo/funk/v2/env"

// Get environment variable with fallback
host := env.GetOr("SERVER_HOST", "localhost")

// Get environment variable or panic if not set
port := env.MustGet("SERVER_PORT")

// Get with multiple fallback names
dbHost := env.Get("DB_HOST", "DATABASE_HOST", "MYSQL_HOST")

Type-Safe Access

import "github.com/pubgo/funk/v2/env"

// Boolean values (supports: true, 1, on, yes)
debug := env.GetBool("DEBUG", "ENABLE_DEBUG")

// Integer values
port := env.GetInt("PORT", "SERVER_PORT")

// Float values
timeout := env.GetFloat("TIMEOUT", "REQUEST_TIMEOUT")

.env File Loading

import "github.com/pubgo/funk/v2/env"

// Load .env file
env.LoadFiles(".env", "config/.env.local")

// Access variables from loaded files
apiKey := env.Get("API_KEY")

Core Concepts

Environment Variable Normalization

The module normalizes environment variable names to ensure consistency:

// These are all equivalent after normalization:
// server-host => SERVER_HOST
// server.host => SERVER_HOST
// server/host => SERVER_HOST
// SERVER-HOST => SERVER_HOST

host := env.Get("server-host")  // Matches SERVER_HOST

Multiple Name Lookup

Functions support multiple names for flexible variable resolution:

// Looks for DB_HOST, then DATABASE_HOST, then MYSQL_HOST
dbHost := env.Get("DB_HOST", "DATABASE_HOST", "MYSQL_HOST")

Safe Type Conversion

Type-safe getters provide graceful handling of conversion errors:

// GetInt returns -1 on conversion error
port := env.GetInt("PORT")
if port == -1 {
    port = 8080  // default
}

// GetBool handles various truthy values
debug := env.GetBool("DEBUG")  // true for "true", "1", "on", "yes"

Advanced Usage

Environment Variable Expansion

import "github.com/pubgo/funk/v2/env"

// Expand environment variables in strings
template := "http://${{HOST}}:${{PORT}}"
expanded := env.Expand(template).UnwrapOr(template)

Environment Manipulation

import "github.com/pubgo/funk/v2/env"

// Set environment variables
env.Set("CUSTOM_VAR", "value").Log()

// Delete environment variables
env.Delete("UNUSED_VAR").Log()

// Check if variable exists
if val, exists := env.Lookup("OPTIONAL_VAR"); exists {
    fmt.Printf("Optional var: %s\n", val)
}

Environment Mapping

import "github.com/pubgo/funk/v2/env"

// Get all environment variables as a map
allVars := env.Map()

// Process all variables
for key, value := range allVars {
    fmt.Printf("%s=%s\n", key, value)
}

API Reference

Core Functions

Type-Safe Getters

File Operations

Utility Functions

Best Practices

1. Use Descriptive Names: Choose clear, descriptive environment variable names
2. Provide Sensible Defaults: Always consider reasonable default values
3. Validate Early: Validate environment variables at startup
4. Document Variables: Document all environment variables your application uses
5. Group Related Variables: Use consistent naming prefixes for related variables
6. Avoid Sensitive Logging: Be careful not to log sensitive environment variables

Integration Patterns

With Configuration

import (
    "github.com/pubgo/funk/v2/env"
    "github.com/pubgo/funk/v2/config"
)

type Config struct {
    Server struct {
        Host string `yaml:"host"`
        Port int    `yaml:"port"`
    } `yaml:"server"`
}

// Environment variables are automatically substituted in config files
cfg := config.Load[Config]()

// Override with environment variables if needed
if host := env.Get("SERVER_HOST"); host != "" {
    cfg.T.Server.Host = host
}

With Feature Flags

import (
    "github.com/pubgo/funk/v2/env"
    "github.com/pubgo/funk/v2/features"
)

// Create feature flag with environment variable default
var debugMode = features.Bool("debug", env.GetBool("DEBUG"), "Enable debug mode")

// Create feature flag with environment variable lookup
var logLevel = features.String("log_level", env.GetOr("LOG_LEVEL", "info"), "Logging level")

With Logging

import (
    "github.com/pubgo/funk/v2/env"
    "github.com/pubgo/funk/v2/log"
)

logger := log.GetLogger("env")

// Log environment variable loading
env.LoadFiles(".env").Log(logger.RecordErr())

// Log specific variable access
host := env.Get("SERVER_HOST")
logger.Info().Str("host", host).Msg("Server host configured")