Конфігурація

Перед цим розділом перегляньте Налаштування — bootstrap і paths.php. Concept Core збирає налаштування з PHP-файлів у config/, застосовує оверрайди середовища (APP_ENV) і змінні з .env. Завантаження виконує ConfigServiceProvider::boot() при першому зверненні до ConfigInterface. Доступ у коді — через DI (ConfigInterface).

Порядок завантаження

Реалізація в ConfigServiceProvider. Кожен наступний крок перекриває попередній для збіглих ключів (окрім кроку 2 — .env лише читається, злиття відбувається на кроці 4).

flowchart LR
    A["1. config/*.php"]
    B["2. .env читається"]
    C["3. config/APP_ENV/*.php"]
    D["4. .env → конфіг"]
    E["app.timezone"]

    A --> B --> C --> D --> E

1. Базовий config/ — усі PHP-файли зливаються Noodlehaus Config.
2. .env — завантажується через vlucas/phpdotenv; APP_ENV визначає папку оверрайду.
3. config/{APP_ENV}/ — якщо каталог існує (dev, production…), його файли зливаються поверх базових.
4. Змінні .env — записуються в конфіг (найвищий пріоритет).
5. Часовий пояс — date_default_timezone_set() з app.timezone.

Мапінг .env → конфіг

Кожна змінна оточення перетворюється на ключ конфігу за правилом «перше підкреслення»: ім’я ділиться на дві частини (ліміт explode('_', ..., 2)), переводиться в нижній регістр, далі з’єднується крапкою.

APP_DEBUG=true     → app.debug
DB_HOST=127.0.0.1   → db.host
LOG_MAX_FILES=14    → log.max_files

Глибше першого рівня через .env не задається: APP_FOO_BAR_BAZ стане app.foo_bar_baz, а не вкладеним масивом. Складні структури — у PHP-файлах config/.

Булеві значення в .env (true, false, 0, 1) коректно читаються через getBool().

Файл .env

Скопіюйте .env.example у .env у корені застосунку. Не комітьте .env у репозиторій — лише приклад.

Оверрайд за APP_ENV

Якщо існує каталог config/{значення APP_ENV}/, усі PHP-файли з нього зливаються поверх базового config/. Імена файлів і структура масивів — такі самі, змінюються лише потрібні ключі.

У skeleton за замовчуванням:

• config/dev/app.php — app.debug = true
• config/dev/telemetry.php — telemetry.enabled = true
• config/production/app.php — app.debug = false
• config/*/components.php — реєстрація компонентів для середовища

config/
├── app.php
├── telemetry.php
├── dev/
│   ├── app.php
│   ├── telemetry.php
│   └── components.php
└── production/
    ├── app.php
    └── components.php

Файли config/

Кожен файл повертає масив; кореневий ключ зазвичай збігається з іменем файлу (без .php).

app.php

db.php

log.php

session.php

Параметри PHP-сесії (SessionServiceProvider → Symfony HttpFoundation → session_start()). Ключі відповідають константам ConfigKey::SESSION_*.

view.php

routes.php

Ключ routes — список файлів маршрутів і route interceptors (див. Маршрутизація, Route interceptors).

return [
    'routes' => [
        'interceptors' => [
            // RouteInterceptorInterface::class,
        ],
        'list' => [
            dirname(__DIR__) . '/routes/web.php',
        ],
    ],
];

components.php

components — список FQCN класів, що реалізують ComponentInterface. У середовищі може бути запис MyComponent::class => MyComponent::class — ядро ітерує значення масиву. Компоненти додають маршрути, шляхи міграцій, seeders, views і CLI-команди через методи ComponentInterface.

return [
    'components' => [
        // AuthAdminComponent::class,
    ],
];

telemetry.php

masking.php

Маскування чутливих даних перед записом у логи і debug-панелі. Читає DataMaskerServiceProvider → DataMaskerInterface. Повний опис — Маскування даних.

// config/masking.php (фрагмент skeleton)
'masking' => [
    'patterns' => [
        '/[a-z0-9_\-\+\.]+@[a-z0-9\-]+\.[a-z]{2,}/i' => '***@***.***',
    ],
    'key_patterns' => [
        '/.*password.*/i',
        '/.*token.*/i',
    ],
    'rules' => [],
],

validator.php

validator.rules — кастомні правила валідації (unique, exists тощо).

caster.php

caster.transformers — список класів кастомних трансформаторів для мапінгу DTO через Valinor. Відповідає ConfigKey::CASTER_TRANSFORMERS.

pagination.php

pagination.per_page — зручне значення за замовчуванням для коду застосунку (у skeleton: 10). Ядро не читає цей ключ автоматично; HttpServiceProvider лише налаштовує Paginator::currentPageResolver і currentPathResolver для Illuminate Pagination.

migrations.php

seeders.php

seeders.list — масив класів сидерів для db:seed (усі разом). Один сидер: db:seed -c "Fully\Qualified\SeederClass" — потрібен повний FQCN.

commands.php

commands — список класів Symfony Console команд ядра та застосунку. У skeleton уже зареєстровані route:list, db:migrate, view:clear тощо.

Ключі ConfigKey

Канонічні ключі, які читає ядро, зібрані в Concept\Core\Foundation\ConfigKey. У власному коді краще посилатися на ці константи, ніж на рядкові літерали:

use Concept\Core\Foundation\ConfigKey;

$debug = $config->getBool(ConfigKey::APP_DEBUG);
$routes = $config->get(ConfigKey::ROUTES_LIST, []);

Повний перелік констант — у вихідному коді code/core/src/Foundation/ConfigKey.php та в README ядра (розділ Configuration).

Доступ у коді

Інжектуйте Concept\Core\Services\Config\Contracts\ConfigInterface:

public function __construct(
    private readonly ConfigInterface $config,
) {}

$debug = $this->config->getBool('app.debug');
$name = $this->config->getString('app.name');
$routes = $this->config->get('routes', []);

Методи: get(), has(), set(), all(), getString(), getInt(), getBool().

Поради для розробки

• Локально встановіть APP_ENV=dev і APP_DEBUG=true у .env.
• Секрети (паролі, API-ключі) — лише в .env, не в config/*.php.
• Спільні значення за замовчуванням — у config/; відмінності середовища — у config/dev/ або config/production/.
• Нові змінні оточення дотримуйтесь конвенції GROUP_NAME → group.name.
• Очистіть кеш Twig після зміни шаблонів: php bin/console.php view:clear.