phpsoftbox/env

Environment variables loader for the PhpSoftBox framework

dev-master 2026-03-05 11:41 UTC

Requires

• php: ^8.4
• phpsoftbox/collection: dev-master
• psr/simple-cache: ^3.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.93
• phpsoftbox/cache: dev-master
• phpsoftbox/cli-app: dev-master
• phpsoftbox/cs-fixer: ^1.1.0
• phpunit/phpunit: ^11.2

MIT

• Anton K.

README

Компонент для загрузки переменных окружения из .env файлов с поддержкой интерполяции, валидации и опционального экспорта в $_ENV/$_SERVER.

Установка

composer require phpsoftbox/env

Быстрый старт

<?php

declare(strict_types=1);

use PhpSoftBox\Env\Environment;

$env = Environment::create(__DIR__ . '/config/env')
    ->setEnvironment(null) // null => APP_ENV
    ->setPrefix('APP_');

$variables = $env->load();

$dbHost = $variables->get('DB_HOST');
$dbPort = $variables->toInt('DB_PORT', 3306);
$debug = $variables->toBool('APP_DEBUG', false);

Производительность и расположение .env

Рекомендуем хранить env-файлы в отдельной папке, например config/env, и передавать её в Environment::create(). Это избавляет от лишнего обхода файловой системы и делает загрузку стабильной на больших проектах.

// Environment::create($baseDir) может рекурсивно обходить ВСЕ поддиректории
// в поисках .env/.env.{env} (в старых версиях или при кастомных ридерах).
// При большом дереве (vendor/node_modules) это даёт секунды TTFB.
// Поэтому .env лучше держать в config/env и читать именно эту папку.
$env = Environment::create($baseDir . '/config/env')
    ->setEnvironment(null)
    ->setPrefix('APP_');

Экспорт в глобальные массивы

По умолчанию библиотека не модифицирует $_ENV/$_SERVER. Экспорт выполняется явно:

$variables = $env->load();
$variables->toGlobals();

Валидация

<?php

use PhpSoftBox\Env\Environment;
use PhpSoftBox\Env\EnvTypeEnum;
use PhpSoftBox\Env\Validator\RequiredValidator;
use PhpSoftBox\Env\Validator\TypeValidator;

$env = Environment::create(__DIR__)
    ->validate(new RequiredValidator(['DB_HOST', 'DB_NAME']))
    ->validate(new TypeValidator([
        'DB_PORT' => EnvTypeEnum::INT,
        'DEBUG' => EnvTypeEnum::BOOL,
    ]));

$variables = $env->load();

Хелпер env()

Хелпер env() читает значения из локального хранилища, затем из $_ENV и $_SERVER. Хранилище автоматически заполняется при load()/safeLoad()/overload().

$variables = $env->load();

$dbHost = env('DB_HOST', 'localhost');