README

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

CloudCastle Config

Неизменяемая конфигурация для PHP 8.1+ с доступом по точечному ключу (db.connections.default) и загрузкой из JSON/XML/YAML/NEON через безопасные парсеры cloud-castle/parser-* (fail-loud, только данные, без выполнения кода). Рекурсивное слияние источников, require() для обязательных ключей, исключения без раскрытия значений.

Установка

composer require cloud-castle/config

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

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

<?php

use CloudCastle\Config\Config;
use CloudCastle\Config\ConfigLoader;

// Доступ по точечному ключу.
$config = new Config([
    'app' => ['name' => 'Demo', 'debug' => true],
    'db' => ['host' => 'localhost', 'port' => 5432],
]);

$config->get('db.host');            // 'localhost'
$config->get('db.timeout', 30);     // 30 (значение по умолчанию)
$config->has('app.debug');          // true
$config->require('db.port');        // 5432 (исключение, если ключа нет)

// Неизменяемость: with()/merge() возвращают новый экземпляр.
$prod = $config
    ->with('app.debug', false)
    ->merge(['db' => ['port' => 6432]]); // рекурсивное слияние, host сохраняется

// Загрузка из файлов (формат по расширению, безопасный разбор).
$fromFile = ConfigLoader::fromFile('/etc/app/database.yaml');
$merged = ConfigLoader::fromDirectory('/etc/app/config'); // все файлы → ветви по имени

Возможности

Точечный доступ: get(), require() (fail-loud), has() по ключам вида db.connections.default.
Неизменяемость: with() и merge() возвращают новый экземпляр — общий конфиг нельзя случайно изменить.
Загрузка из файлов: ConfigLoader::fromFile() и fromDirectory() — формат определяется по расширению (json/xml/yaml/yml/neon).
Безопасный разбор: файлы читают парсеры cloud-castle/parser-* — только данные, без выполнения кода, объектов и XXE.
Рекурсивное слияние: merge() объединяет отображения по ключам, списки заменяет целиком.
Исключения не раскрывают значения — в сообщении только имя ключа/причина.

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

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

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

Возможность	🏆 CloudCastle	adbario	dflydev	illuminate	selective	symfony
Доступ по точечному ключу (db.port)	✅	✅	✅	✅	✅	❌
Неизменяемость (модификаторы возвращают новый экземпляр)	✅	❌	❌	❌	✅	❌
Загрузка из файлов JSON/XML/YAML/NEON	✅	❌	❌	❌	❌	❌
Безопасный разбор файлов (без выполнения кода и инъекций)	✅	❌	❌	❌	❌	❌
Рекурсивное слияние источников	✅	✅	✅	❌	❌	❌
Всего	🏆 5	2	2	1	2	0

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

Свойство	🏆 CloudCastle	adbario	dflydev	illuminate	selective	symfony
Безопасный разбор конфигов (нет выполнения кода при загрузке)	✅	❌	❌	❌	❌	❌
Отклонение опасных конструкций (XXE, объекты в YAML/NEON)	✅	❌	❌	❌	❌	❌
Fail-loud на отсутствующем обязательном ключе	✅	❌	❌	❌	✅	✅
Неизменяемость (нет случайной мутации общего конфига)	✅	❌	❌	❌	✅	❌
Исключения не раскрывают значения (только имя ключа)	✅	❌	❌	❌	❌	❌
Всего	🏆 5	0	0	0	2	1

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

обёртка конфигурации + чтение двух вложенных значений, 100 000 раз (минимум из 4).

Решение	Время (мс)	Итог
🏆 CloudCastle	1 637,1	быстрейшее среди библиотек
selective	2 111,4	аналог
dflydev	2 885,5	аналог
adbario	4 384,1	аналог
symfony	5 620,9	аналог
illuminate	6 751,6	аналог

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

Инкрементальный пик при удержании 100 000 результатов (изолированный процесс).

Решение	Пиковая память (KB)	Итог
🏆 symfony	4 100	легчайшее среди библиотек
CloudCastle	10 602	аналог
selective	10 608	аналог
illuminate	10 611	аналог
dflydev	10 618	аналог
adbario	12 982	аналог

Коротко

Неизменяемый доступ к конфигурации по точечному ключу с безопасной загрузкой из файлов (JSON/XML/YAML/NEON) и рекурсивным слиянием — то, чего нет у чистых dot-контейнеров. Лидирует по функционалу, безопасности и скорости; по памяти — легчайший среди реальных config-контейнеров (тоньше illuminate/adbario), а меньший расход только у symfony/property-access — но это stateless-аксессор без контейнера, загрузки и слияния (нулевой функционал по нашей матрице).

Плюсы, минусы и когда применять

Сильные стороны:

Функционал = объединение аналогов — точечный доступ + неизменяемость + загрузка JSON/XML/YAML/NEON + безопасный разбор + слияние источников; у аналогов — лишь часть из этого.
Безопасность — разбор файлов без выполнения кода, отклонение XXE/опасных конструкций, fail-loud на отсутствующем обязательном ключе, исключения не раскрывают значения (лидер по таблице безопасности).
Производительность — быстрейшее точечное чтение среди аналогов (isset-путь без лишних вызовов функций), опережает selective, dflydev, adbario и illuminate.
Неизменяемость — модификаторы возвращают новый экземпляр, общий конфиг не мутирует.
Память — легчайший среди реальных config-контейнеров (обёртка тоньше, чем у illuminate/adbario); замер удерживает сами объекты-обёртки, а не производную строку.

Слабые стороны (честно):

Память vs stateless-аксессор — symfony/property-access расходует ещё меньше, так как вообще не создаёт объект-контейнер (работает по вашему массиву); плата за это — отсутствие загрузки файлов, слияния, неизменяемости и безопасного разбора.
Экосистема — illuminate/config глубже интегрирован в Laravel (готовые провайдеры/фасады), здесь интеграцию с фреймворком нужно делать самостоятельно.
Не микропакет — если нужен только dot-доступ без загрузки файлов и слияния, узкий контейнер (adbario/dflydev) минималистичнее по объёму кода.

Когда применять. Там, где конфигурация приходит из файлов недоверенного/внешнего происхождения и важны безопасный разбор, предсказуемость, неизменяемость и слияние источников. Для сверхлёгкого dot-доступа без загрузки файлов подойдёт узкий контейнер (adbario/dflydev), для Laravel — illuminate/config.

Разработка

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

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

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

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

Лицензия