Configuration

Before this section, review Setup — bootstrap and paths.php. Concept Core collects settings from PHP files in config/, applies environment overrides (APP_ENV), and variables from .env. Loading is performed by ConfigServiceProvider::boot() on the first access to ConfigInterface. Access in code is through DI (ConfigInterface).

Loading order

Implemented in ConfigServiceProvider. Each subsequent step overrides the previous one for matching keys (except step 2 — .env is only read; merging happens at step 4).

flowchart LR
    A["1. config/*.php"]
    B["2. .env is read"]
    C["3. config/APP_ENV/*.php"]
    D["4. .env → config"]
    E["app.timezone"]

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

1. Base config/ — all PHP files are merged with Noodlehaus Config.
2. .env — loaded via vlucas/phpdotenv; APP_ENV determines the override folder.
3. config/{APP_ENV}/ — if the directory exists (dev, production…), its files are merged on top of the base config.
4. .env variables — written into config (highest priority).
5. Timezone — date_default_timezone_set() from app.timezone.

.env → config mapping

Each environment variable is converted to a config key using the “first underscore” rule: the name is split into two parts (limit explode('_', ..., 2)), lowercased, then joined with a dot.

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

Nesting deeper than the first level is not supported via .env: APP_FOO_BAR_BAZ becomes app.foo_bar_baz, not a nested array. Complex structures belong in config/ PHP files.

Boolean values in .env (true, false, 0, 1) are read correctly via getBool().

.env file

Copy .env.example to .env in the application root. Do not commit .env to the repository — only the example file.

Override by APP_ENV

If the directory config/{APP_ENV value}/ exists, all PHP files from it are merged on top of the base config/. File names and array structure are the same; only the required keys change.

In skeleton by default:

• config/dev/app.php — app.debug = true
• config/dev/telemetry.php — telemetry.enabled = true
• config/production/app.php — app.debug = false
• config/*/components.php — component registration per environment

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

config/ files

Each file returns an array; the root key usually matches the file name (without .php).

app.php

db.php

log.php

session.php

PHP session parameters (SessionServiceProvider → Symfony HttpFoundation → session_start()). Keys correspond to ConfigKey::SESSION_* constants.

view.php

routes.php

The routes key is a list of route files and route interceptors (see Routing, Route interceptors).

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

components.php

components is a list of FQCN classes implementing ComponentInterface. The environment may have MyComponent::class => MyComponent::class — the core iterates over array values. Components add routes, migration paths, seeders, views, and CLI commands via ComponentInterface methods.

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

telemetry.php

masking.php

Masking sensitive data before writing to logs and debug panels. Read by DataMaskerServiceProvider → DataMaskerInterface. Full description — Data masking.

// config/masking.php (skeleton fragment)
'masking' => [
    'patterns' => [
        '/[a-z0-9_\-\+\.]+@[a-z0-9\-]+\.[a-z]{2,}/i' => '***@***.***',
    ],
    'key_patterns' => [
        '/.*password.*/i',
        '/.*token.*/i',
    ],
    'rules' => [],
],

validator.php

validator.rules — custom validation rules (unique, exists, etc.).

caster.php

caster.transformers — list of custom transformer classes for Valinor DTO mapping. Mapped to ConfigKey::CASTER_TRANSFORMERS.

pagination.php

pagination.per_page — convenient default for application code (in skeleton: 10). The core does not read this key automatically; HttpServiceProvider only configures Paginator::currentPageResolver and currentPathResolver for Illuminate Pagination.

migrations.php

seeders.php

seeders.list — array of seeder classes for db:seed (all at once). Single seeder: db:seed -c "Fully\Qualified\SeederClass" — full FQCN required.

commands.php

commands — list of Symfony Console command classes from core and application. Skeleton already registers route:list, db:migrate, view:clear, etc.

ConfigKey constants

Canonical keys read by the core are collected in Concept\Core\Foundation\ConfigKey. In your own code, prefer these constants over string literals:

use Concept\Core\Foundation\ConfigKey;

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

Full list of constants — in source code code/core/src/Foundation/ConfigKey.php and in the core README (Configuration section).

Access in code

Inject 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', []);

Methods: get(), has(), set(), all(), getString(), getInt(), getBool().

Development tips

• Locally set APP_ENV=dev and APP_DEBUG=true in .env.
• Secrets (passwords, API keys) — only in .env, not in config/*.php.
• Shared defaults — in config/; environment differences — in config/dev/ or config/production/.
• For new environment variables, follow the GROUP_NAME → group.name convention.
• Clear Twig cache after template changes: php bin/console.php view:clear.