Configuration
Introduction
A Windwalker application is configured in two layers. Environment variables hold values that change between machines, such as database credentials or the debug switch. PHP configuration files hold the application's structure, such as routing, security, and package settings. The files read the environment variables, so one codebase can run in development, staging, and production with different values.
Configuration files return plain PHP arrays. Each application reads them at boot and exposes them through the config() method:
$name = $app->config('app.name');
$debug = $app->config('app.debug');Dotted keys address nested values, so app.name reads the name key inside the app section.
The etc Directory
All configuration lives in the etc/ directory of the project:
define.php: defines the path constants, such asWINDWALKER_ROOTandWINDWALKER_ETC, and loads the.envfiles. The web entry pointwww/index.phpincludes it.runtime.config.php: runtime settings loaded byRuntime::loadConfig()before the application starts, such as the path aliases and the HTTP server.config.php: the entry point that merges the files inconf/,packages/, anddi.config.phpinto one array.conf/: the core settings, one file per topic, such asapp,security,routing, andlogs. Each file becomes a top-level key.packages/: one file per installed package, such asaccessorcache. Every file is merged automatically.app/: the settings for each application entry point.main.config.phpconfigures the web application,console.config.phpconfigures the console application, andwindwalker.config.phpholds the shared settings that both files include.di/: one file per service factory group. The files are merged intodi.config.php, so new services do not require editing a long list.di.config.php: the dependency injection settings, such as the factories, providers, bindings, and aliases. It is stored in thediconfiguration key.custom.config.php: optional, not present by default. When it exists inconf/, it overrides any section.
The rest of this page explains each part in detail.
Environment Configuration
Environment variables provide the values that change between machines, such as database credentials and the debug switch. Windwalker loads them from .env files in the project root, and the configuration files read them with the env() helper. The environment variables page covers the loading order, the APP_ENV and APP_DEBUG settings, and the handling of secrets.
App Configuration
Configuration Files
Configuration files live in etc/. The entry point etc/config.php merges them into one array. Each file is a top-level key:
etc/conf/app.config.phpbecomesapp.etc/conf/security.config.phpbecomessecurity.etc/conf/routing.config.phpbecomesrouting.etc/di.config.phpbecomesdi.
A file returns an array of settings:
// etc/conf/app.config.php
use Windwalker\Core\Provider\DateTimeProvider;
return [
'name' => 'Windwalker',
'timezone' => env('APP_TIMEZONE', 'UTC'),
'providers' => [
DateTimeProvider::class,
],
];Read a value with its path, such as $app->config('app.timezone').
Files merged last overwrite earlier keys with the same name. A conf/custom.config.php file, when present, is merged after all other files, so it can override any top-level section.
TIP
Keep environment-specific values in .env files and let configuration files read them. Avoid editing the arrays for each environment.
Packages Configuration
Each installed package can ship its own configuration in etc/packages/. Every *.php file in that folder is loaded automatically, and its array is merged into the top level, so you do not need to list the files in etc/config.php.
A package file often uses the ConfigModule attribute to control when it is loaded:
// etc/packages/cache.config.php
use Windwalker\Core\Attributes\ConfigModule;
return #[ConfigModule(
name: 'cache',
enabled: true,
env: ['dev', 'prod'],
)]
static fn() => [
'driver' => 'file',
];ConfigModule controls the following:
enabled: turns the module on or off.env: loads the module only in the listedAPP_ENVvalues.belongsTo: loads the module only when the named package or class is installed.priority: sets the merge order when several modules compete.
The env filter checks APP_ENV, and a missing value is treated as prod. The module's callback is not called until the configuration is read, so an expensive array does not slow down unrelated requests.
For the settings each bundled package accepts, see the package configuration reference.
INFO
A package's belongsTo value can be a Composer package name, such as vendor/package, or a class name. The module is skipped when the package or class is not available.