README

🇷🇺 Русский · 🇬🇧 English · 🇩🇪 Deutsch · 🇫🇷 Français · 🇪🇸 Español · 🇮🇹 Italiano

CloudCastle Env

Загрузка и типизированный доступ к переменным окружения для PHP 8.1+. Совместимый с .env разбор (кавычки, комментарии, интерполяция ${VAR}), типизированные геттеры, валидация, фильтры, иммутабельное хранилище. Нулевые внешние зависимости.

Установка

composer require cloud-castle/env

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

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

<?php

use CloudCastle\Env\Dotenv;
use CloudCastle\Env\Env;

// Загрузка .env (иммутабельно: существующее окружение не перезаписывается).
Dotenv::createImmutable('/path/to/.env')->load();

// Типизированный доступ — без ручного приведения строк.
$debug   = Env::getBool('APP_DEBUG', false);
$port    = Env::getInt('DB_PORT', 5432);
$ratio   = Env::getFloat('RATIO', 1.0);
$flags   = Env::getList('FEATURE_FLAGS');        // ['a','b','c']
$name    = Env::getString('APP_NAME', 'app');

// Валидация обязательных переменных на старте приложения.
Dotenv::createImmutable('/path/to/.env')
    ->required(['APP_KEY', 'DB_HOST'])
    ->notEmpty()
    ->assert();

Dotenv::createImmutable('/path/to/.env')
    ->required('DB_PORT')
    ->isInteger()
    ->assert();

Возможности

Совместимый разбор .env: пары, одинарные/двойные кавычки, экранирование, комментарии, пустые значения, интерполяция ${VAR} — результат совпадает с vlucas/phpdotenv, symfony/dotenv и josegonzalez/dotenv (см. интероп-тесты).
Типизированные геттеры: getString, getInt, getFloat, getBool, getList — вместо ручного приведения строковых значений.
Валидация: required / ifPresent + notEmpty, isInteger, isFloat, isBoolean, allowedValues, allowedRegexValues.
Три режима хранилища: иммутабельный, мутабельный и array-backed (изолированное хранилище в памяти, не трогающее $_ENV/putenv).
Фильтры: произвольная пост-обработка загруженных значений.
Безопасность: иммутабельный режим по умолчанию защищает от случайной перезаписи окружения; никакие ПД/секреты не логируются.

Сравнение с аналогами

Все таблицы ниже сгенерированы автоматически из честных сравнительных тестов (benchmarks/compare.php) на ОДИНАКОВОЙ операции для всех аналогов, PHP 8.1.34, без Xdebug.

1. Функциональность

Возможность	🏆 CloudCastle	symfony	vlucas	m1/env	josegonzalez	devcoder	ini¹
Приведение к нативным типам (bool/int/float/null)	✅	❌	❌	✅	✅	✅	❌
Схемная валидация переменных (типы + обязательность)	✅	❌	✅	❌	❌	❌	❌
Интерполяция ${VAR} со вложенностью	✅	✅	✅	✅	✅	❌	❌
Множественная загрузка файлов с приоритетом	✅	✅	✅	❌	❌	❌	❌
Нулевые внешние runtime-зависимости	✅	✅	❌	✅	✅	✅	✅
Всего	🏆 5	3	3	3	3	2	1

2. Безопасность и корректность

Свойство	🏆 CloudCastle	symfony	vlucas	m1/env	josegonzalez	devcoder	ini¹
Изоляция от глобального состояния по умолчанию (без записи в $_ENV/putenv)	✅	❌	✅	✅	✅	❌	✅
Типизированное исключение при синтаксической ошибке	✅	✅	✅	✅	✅	❌	❌
Безопасная интерполяция (только объявленные переменные, без eval)	✅	✅	✅	✅	✅	❌	❌
Иммутабельность репозитория загруженных значений	✅	❌	✅	❌	❌	❌	❌
Нулевые внешние runtime-зависимости (меньше поверхность атаки)	✅	✅	❌	✅	✅	✅	✅
Всего	🏆 5	3	4	4	4	1	2

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

Разбор .env (12 переменных), 100 000 раз (минимум из 4).

Решение	Время (мс)	Итог
ini¹	240,8	базовый уровень (не библиотека)
🏆 CloudCastle	988,7	быстрейшее среди библиотек
devcoder	2 201,3	аналог
m1/env	3 723,7	аналог
symfony	3 986,9	аналог
josegonzalez	5 135,1	аналог
vlucas	10 699,3	аналог

4. Потребление памяти

Пик памяти на 100 000 разборов (изолированный процесс, только целевая библиотека).

Решение	Пиковая память (KB)	Итог
🏆 CloudCastle	6 977	легчайшее среди библиотек
symfony	6 977	аналог
vlucas	6 977	аналог
devcoder	6 978	аналог
ini¹	6 978	базовый уровень (не библиотека)
josegonzalez	9 638	аналог
m1/env	10 173	аналог

¹ Базовый уровень (нативные вызовы/примитивы без полноты решения) показан для контекста и не претендует на победу среди библиотек-аналогов.

Вывод: CloudCastle Env — самый быстрый среди библиотек и самый лёгкий по памяти, единственный объединяющий совместимый разбор, типизированные геттеры, схемную валидацию и фильтры при нулевых внешних зависимостях.

Разработка

composer install
composer check    # линтеры + статический анализ + тесты
composer fix      # автоисправления (Rector, PHP CS Fixer, PHPCBF)
composer ci       # полный CI-пайплайн локально

Полный список команд с описаниями: composer run-script --list.

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

Репозиторий: https://gitverse.ru/cloud-castle/env
История изменений: CHANGELOG.md
Как внести вклад: CONTRIBUTING.md
Кодекс поведения: CODE_OF_CONDUCT.md
Политика безопасности: SECURITY.md

Лицензия