README

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, изолированные замеры без Xdebug (composer compare). Метрика — ops/sec (больше — лучше); файловые аналоги включают ввод-вывод файла.

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

Полное сравнение и разбор по каждой возможности — в 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