CloudCastle Env

Zero-dependency загрузчик .env для PHP 8.1+. Разбор с интерполяцией, приведение типов, иммутабельное хранилище, валидация и фильтры — весь жизненный цикл конфигурации приложения в едином API, без единой runtime-зависимости.

Установка

composer require cloudcastle/env

Требуется PHP 8.1+.

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

<?php

use CloudCastle\Env\Env;

// Загрузить .env (иммутабельно: не перезаписывает системное окружение)
Env::load(__DIR__ . '/.env');

// Типизированное чтение
$debug = Env::getBool('APP_DEBUG');          // "true" → true
$port  = Env::getInt('DB_PORT', 5432);       // с значением по умолчанию
$hosts = Env::getList('TRUSTED_HOSTS');      // "a,b,c" → ['a', 'b', 'c']

// Проверка обязательных переменных (все ошибки — разом)
Env::required(['APP_KEY', 'DB_HOST'])->notEmpty();
Env::required('DB_PORT')->isInteger();

Возможности

• Разбор .env — кавычки, export, комментарии, многострочные значения, интерполяция ${VAR}/$VAR с экранированием \$.
• Приведение типов — авто-cast bool/int/float/null и типизированные геттеры (getInt/getBool/getFloat/getList) с обратимостью (007/3.0/1e5 → строка).
• Хранилище — адаптеры $_ENV/$_SERVER/putenv/массив, иммутабельность по умолчанию.
• Валидация — required/notEmpty/isInteger/allowedValues/allowedRegexValues.
• Фильтры имён — префикс, регистр, переименование, произвольный callable.
• Zero-dependency — только PHP 8.1+, без единой runtime-зависимости.

Функционально пакет покрывает возможности всех пяти сравниваемых аналогов вместе взятых: vlucas/phpdotenv, symfony/dotenv, josegonzalez/dotenv, m1/env, devcoder-xyz/php-dotenv.

Возможности против аналогов

Сводная таблица (генерируется автоматически из tools/features-data.php; значения выверены по коду и документации аналогов). Легенда: ✅ полностью · ⚠️ частично · 🔌 адаптер · ❌ нет · — неприменимо.

Сгенерировано из tools/features-data.php (факты о поддержке). Легенда: ✅ полностью · ⚠️ частично · 🔌 адаптер · ❌ нет · — неприменимо.

Разбор синтаксиса .env

Функция	Env	vlucas	symfony	josegonzalez	m1	devcoder	🏆 Победитель
Комментарии # и пустые строки	✅	✅	✅	✅	✅	⚠️	Паритет
Префикс export	✅	✅	✅	✅	✅	❌	Паритет
Двойные кавычки с экранированием	✅	✅	✅	✅	✅	⚠️	Паритет
Одинарные кавычки (литерал)	✅	✅	✅	✅	✅	⚠️	Паритет
Многострочные значения в кавычках	✅	✅	✅	❌	❌	❌	Env, vlucas, symfony
Инлайн-комментарии VAR=val # …	✅	✅	✅	✅	⚠️	❌	Паритет
Интерполяция ${VAR} / $VAR	✅	✅	✅	⚠️	⚠️	❌	Env, vlucas, symfony
Экранирование \$ (без подстановки)	✅	✅	✅	❌	❌	❌	Env, vlucas, symfony

Приведение типов

Функция	Env	vlucas	symfony	josegonzalez	m1	devcoder	🏆 Победитель
Авто-cast bool/int/float/null	✅	❌	❌	❌	❌	✅	Env, devcoder
Обратимость (007/3.0/1e5 → строка)	✅	—	—	—	—	⚠️	Env
Типизированные геттеры getInt/getBool/getList	✅	❌	❌	❌	❌	❌	Env

Хранилище и адаптеры

Функция	Env	vlucas	symfony	josegonzalez	m1	devcoder	🏆 Победитель
Адаптеры $_ENV / $_SERVER / putenv	✅	✅	⚠️	🔌	❌	⚠️	Env, vlucas
Иммутабельность (не перезаписывать)	✅	✅	✅	❌	❌	❌	Паритет
Изолированное хранилище в памяти	✅	✅	❌	✅	✅	❌	Паритет

Валидация

Функция	Env	vlucas	symfony	josegonzalez	m1	devcoder	🏆 Победитель
Обязательные переменные (required)	✅	✅	⚠️	✅	❌	❌	Паритет
Проверки isInteger/isBoolean/isFloat	✅	✅	❌	⚠️	❌	❌	Env, vlucas
allowedValues / регулярные выражения	✅	✅	❌	❌	❌	❌	Env, vlucas

Фильтры и преобразование имён

Функция	Env	vlucas	symfony	josegonzalez	m1	devcoder	🏆 Победитель
Префикс / регистр / переименование ключей	✅	❌	❌	✅	❌	❌	Env, josegonzalez
Произвольный callable-фильтр	✅	❌	❌	✅	❌	❌	Env, josegonzalez

Зависимости и качество

Функция	Env	vlucas	symfony	josegonzalez	m1	devcoder	🏆 Победитель
Runtime-зависимости (0 — лучше)	✅	❌	✅	⚠️	✅	✅	Env, symfony, m1, devcoder
Единый API: разбор + типы + валидация + фильтры	✅	⚠️	❌	⚠️	❌	❌	Env

Производительность

Разбор типового .env, изолированные замеры без Xdebug (composer compare). Метрика — ops/sec (больше — лучше); файловые аналоги включают ввод-вывод файла.

Сгенерировано из composer compare (PHP 8.2.32). Правки в блоке будут перезаписаны.

Сценарий	cloudcastle/env	devcoder-xyz/php-dotenv	m1/env	josegonzalez/dotenv	symfony/dotenv	vlucas/phpdotenv
Разбор типового .env (20000 итераций)	67474 ops/s	34975 ops/s	18462 ops/s	14094 ops/s	13747 ops/s	6064 ops/s

Полное сравнение и разбор по каждой возможности — в Wiki: Сравнение.

Заключение: когда что выбирать

Сильные стороны cloudcastle/env — единственный пакет, объединяющий полный разбор .env (кавычки, многострочные значения, интерполяция с экранированием), приведение типов с обратимостью, иммутабельное хранилище с четырьмя адаптерами, текучую валидацию и фильтры имён — при нуле runtime-зависимостей. Управляющие символы экранируются в сообщениях об ошибках (защита логов), подстановка команд при интерполяции не выполняется.

Производительность: лидер разбора — ~67 000 разборов/сек, быстрее vlucas/phpdotenv в ~11×, symfony/dotenv в ~5×, m1/env в ~3.6×, josegonzalez/dotenv в ~4.8×, devcoder-xyz/php-dotenv в ~1.9× (последний — с файловым вводом-выводом). Замеры изолированные, без Xdebug (composer compare).

Слабые стороны — пакет молодой; отдельные экосистемные интеграции (Symfony-bundle, Laravel service provider) пока не поставляются; поддерживается только формат .env (не YAML/JSON/INI — для них отдельные пакеты экосистемы).

Честные рекомендации:

• Нужен полный цикл конфигурации (разбор + типы + валидация + фильтры) без зависимостей — cloudcastle/env.
• Глубокая экосистема Laravel вокруг .env — vlucas/phpdotenv.
• Проект на Symfony с интеграцией фреймворка — symfony/dotenv.
• Нужны фильтры имён при простом разборе — josegonzalez/dotenv или cloudcastle/env.
• Минимальный парсер строки без хранилища — m1/env.
• Типизация через процессоры при простой загрузке из файла — devcoder-xyz/php-dotenv.

Документация

• Wiki — руководство пользователя
• Быстрый старт
• Архитектура
• API-документация

Качество

Пакет придерживается production-стандартов: строгая типизация, полный статический анализ (PHPStan max, Psalm level 1, PHPMD, Deptrac, Rector), покрытие тестами ≥ 98 % на каждый файл и мутационное тестирование (Infection MSI ≥ 98 %). Матрица CI — PHP 8.1–8.5.

composer ci        # полный пайплайн качества
composer check     # быстрые проверки перед коммитом
composer test      # тесты (unit + integration + security + load)

Контакты

• Email — alex-4-17@yandex.ru
• VK — https://vk.com/leha_zorin
• Telegram — @CloudCastle85
• Телефон — +79872763991
• Сетка — https://set.ki/LdYRz76

Поддержать проект

Реквизиты для поддержки автора — в DONATE.md.

Contributors

Спасибо всем, кто вносит вклад в проект:

Список ведётся по спецификации all-contributors.

Лицензия

MIT © CloudCastle