README

Validate required environment variables with type checking and defaults.

Requirements

• PHP 8.2+

Installation

composer require philiprehberger/env-validator

Usage

Required Variables

Check that environment variables are present:

use PhilipRehberger\EnvValidator\EnvValidator;

$result = EnvValidator::required(['APP_KEY', 'DATABASE_URL', 'REDIS_HOST'])
    ->validate();

if (!$result->passed) {
    echo 'Missing: ' . implode(', ', $result->missing);
}

Schema with Type Rules

Define variables with type validation in a single call:

$result = EnvValidator::schema([
    'APP_PORT' => 'int',
    'APP_DEBUG' => 'bool',
    'APP_URL' => 'url',
    'ADMIN_EMAIL' => 'email',
])->validate();

Default Values

Provide fallback values for variables that may not be set:

$result = EnvValidator::required(['APP_PORT', 'APP_ENV'])
    ->defaults([
        'APP_PORT' => '8080',
        'APP_ENV' => 'production',
    ])
    ->validate();

Optional Variables

Optional variables generate warnings but do not cause validation failure:

$result = EnvValidator::required(['DATABASE_URL'])
    ->optional(['CACHE_DRIVER', 'QUEUE_CONNECTION'])
    ->validate();

// $result->warnings contains notices about unset optional vars

Type Validation

Add type rules to individual variables:

$result = EnvValidator::required(['API_PORT', 'API_URL'])
    ->type('API_PORT', 'int')
    ->type('API_URL', 'url')
    ->validate();

Validate or Fail

Throw an exception if validation fails:

use PhilipRehberger\EnvValidator\Exceptions\EnvValidationException;

try {
    EnvValidator::required(['APP_KEY', 'DATABASE_URL'])
        ->validateOrFail();
} catch (EnvValidationException $e) {
    echo $e->getMessage();
    // Access the full result
    $result = $e->result;
}

IP Validation

Validate IP addresses with specific version constraints:

$result = EnvValidator::required(['SERVER_IP', 'GATEWAY_V4', 'GATEWAY_V6'])
    ->type('SERVER_IP', 'ip')
    ->type('GATEWAY_V4', 'ipv4')
    ->type('GATEWAY_V6', 'ipv6')
    ->validate();

Custom Validation Rules

Define your own validation logic with a callable:

$result = EnvValidator::required(['APP_SECRET'])
    ->custom('APP_SECRET', fn (string $value) => strlen($value) >= 32, 'Secret must be at least 32 characters.')
    ->validate();

Enum Validation

Validate that a value matches one of a backed enum's cases:

enum Environment: string
{
    case Production = 'production';
    case Staging = 'staging';
    case Development = 'development';
}

$result = EnvValidator::required(['APP_ENV'])
    ->enum('APP_ENV', Environment::class)
    ->validate();

Dependency Rules

Make variables conditionally required based on other variables:

// DB_HOST is only required when DB_DRIVER is set
$result = EnvValidator::required(['DB_DRIVER', 'DB_HOST'])
    ->dependsOn('DB_HOST', 'DB_DRIVER')
    ->validate();

// REDIS_HOST is required when CACHE_DRIVER equals "redis"
$result = EnvValidator::required(['CACHE_DRIVER', 'REDIS_HOST'])
    ->requiredIf('REDIS_HOST', 'CACHE_DRIVER', 'redis')
    ->validate();

// APP_SECRET is required unless APP_ENV equals "local"
$result = EnvValidator::required(['APP_ENV', 'APP_SECRET'])
    ->requiredUnless('APP_SECRET', 'APP_ENV', 'local')
    ->validate();

.env File Parsing

Validate a .env file without loading it into the environment:

$result = EnvValidator::fromFile('/path/to/.env')
    ->type('APP_PORT', 'int')
    ->type('APP_URL', 'url')
    ->validate();

The parser handles comments, quoted values, multiline values, export prefix, and ${VAR} interpolation.

Environment Profiles

Register named validation profiles for different environments:

// Register profiles
EnvValidator::profile('web', [
    'APP_URL' => 'url',
    'APP_PORT' => 'int',
    'APP_DEBUG' => 'bool',
]);

EnvValidator::profile('worker', [
    'QUEUE_CONNECTION' => 'string',
    'REDIS_HOST' => 'string',
]);

// Validate against a profile
$result = EnvValidator::validateProfile('web');

Supported Types

API

EnvValidator

PendingValidation

ValidationResult

Development

composer install
vendor/bin/phpunit
vendor/bin/pint --test
vendor/bin/phpstan analyse

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT