devinci-it/envngine

Tiny schema-first environment loader for PHP apps

v1.0.0 2026-05-11 15:46 UTC

Requires

• php: >=8.1
• vlucas/phpdotenv: ^5.6

MIT

README

Tiny schema-first environment loader for PHP 8.1+.

Quick Flow

1. Add your schema in config/env.php.
2. Boot the registry with Env::boot('config/env.php').
3. Read values with Env::get(), Env::string(), Env::int(), Env::bool(), or Env::array().
4. Generate or secure .env with the provided CLI tools if needed.

Builder Config

config/env.php can return a direct builder chain, which is the easiest format to remember:

<?php

use DevinciIT\EnvNgine\EnvBuilder;

return EnvBuilder::make()
    ->string('APP_NAME')
    ->default('EnvNgine App')
    ->description('Application display name')

    ->string('APP_ENV')
    ->default('local')

    ->bool('APP_DEBUG')
    ->default(false)

    ->int('APP_PORT')
    ->default(8000)
    ->required()
    ->description('Application port')

    ->array('ALLOWED_HOSTS')
    ->default(['localhost'])
    ->description('Comma-separated list of allowed hostnames')

    ->string('DB_HOST')
    ->required()
    ->default('127.0.0.1')
    ->description('Database hostname');

Access Values

Boot once, then read values anywhere:

Env::boot(__DIR__ . '/config/env.php');

$appName = Env::string('APP_NAME', 'My App');
$appEnv = Env::string('APP_ENV', 'local');
$appDebug = Env::bool('APP_DEBUG', false);
$appPort = Env::int('APP_PORT', 8000);
$hosts = Env::array('ALLOWED_HOSTS', ['localhost']);
$dbHost = Env::string('DB_HOST', '127.0.0.1');

Helpers:

env_boot(__DIR__ . '/config/env.php');
$registry = env_registry();
$value = Env::get('KEY', 'fallback');

CLI Tools

• php bin/generate-env.php generates .env from config/env.php.
• php bin/secure-env.php applies permissions and optional owner/group changes.
• Composer shortcuts are available through the env:generate, env:secure, and env:prepare scripts.

Caveats

• Boot is lazy by default, but calling Env::boot() locks the registry.
• config/env.php is only loaded from the consumer project path or when passed explicitly.
• Missing .env or missing schema files produce a clear bootstrap error instead of a raw dotenv exception.
• Access warnings are meant as diagnostics, so they are intentionally visible in CLI output.
• Array values are parsed from comma-separated strings.
• Defaults are applied from the schema when a key is missing.
• The registry becomes immutable after boot, so set runtime values before locking if you need to.

Package Surface

• Env::boot() / Env::bootWithSchema()
• Env::get() / Env::string() / Env::int() / Env::bool() / Env::array()
• env_boot() / env_registry()
• bin/generate-env.php
• bin/secure-env.php

License

MIT