Architecture

Архитектура

Поток данных

.env файл ──▶ EnvParser ──▶ [фильтры] ──▶ Repository ──▶ адаптеры ($_ENV/$_SERVER/putenv/array)
                 │                              ▲
          интерполяция ${VAR}           чтение через фасад Env
                                               │
                                        TypeCaster (bool/int/float/null)

1. EnvParser разбирает синтаксис .env: кавычки, export, комментарии, многострочные значения, интерполяция ${VAR}/$VAR.
2. Фильтры (FilterInterface) преобразуют имена переменных.
3. Repository пишет значения в набор адаптеров с учётом иммутабельности.
4. Env (статический фасад) читает значения, приводя типы через TypeCaster.
5. Validator проверяет присутствие и формат обязательных переменных.

Пространство имён

Пакет использует PSR-4 namespace CloudCastle\Env\ (каталог src/) с подслоями:

• CloudCastle\Env\Contract\ — интерфейсы: ParserInterface, RepositoryInterface, AdapterInterface, FilterInterface;
• CloudCastle\Env\Exception\ — исключения: InvalidFileException, InvalidValueException, ValidationException (все реализуют EnvExceptionInterface);
• CloudCastle\Env\Repository\ — Repository и адаптеры в Repository\Adapter\;
• CloudCastle\Env\Filter\ — фильтры имён переменных;
• CloudCastle\Env\… — фасад Env, Dotenv, EnvParser, TypeCaster, Validator.

Архитектурные границы проверяются Deptrac: реализация зависит от Contract/Exception, но не наоборот.

Ключевые решения

• Zero-dependency. Пакет не имеет runtime-зависимостей — только PHP 8.1+.
• Адаптеры-источники. Один Repository объединяет $_ENV, $_SERVER, putenv и массив в памяти; чтение — из первого попавшегося, запись — во все.
• Иммутабельность по умолчанию. Загрузка .env не перезаписывает системное окружение.
• Обратимое приведение типов. 007, 3.0, 1e5 остаются строками, чтобы не терять данные при round-trip.
• Разбор до снятия экранирования. Интерполяция применяется до unescape, поэтому \$ не подставляется, а становится литеральным $.

Тесты

CloudCastle\Env\Tests\ (каталог tests/) разделён на наборы: Unit, Integration, Security, Load, Performance.

Принципы

• Строгая типизация, declare(strict_types=1) в каждом файле.
• Ноль runtime-зависимостей.
• Публичный API документирован PHPDoc на русском.