Configuration
Marko uses PHP files for configuration — not YAML, not JSON, not .env directly. Config defaults go in each module’s config/ directory, and PHP config files give you type safety, IDE autocompletion, and a single source of truth.
Config Files
Section titled “Config Files”Configuration lives in PHP files that return arrays:
<?php
declare(strict_types=1);
use Marko\Config\Env;
return [ 'driver' => 'pgsql', 'host' => Env::string('DB_HOST', 'localhost'), 'port' => Env::int('DB_PORT', 5432, min: 1, max: 65535), 'database' => Env::string('DB_DATABASE', 'marko'), 'username' => Env::string('DB_USERNAME', 'marko'), 'password' => Env::string('DB_PASSWORD', ''),];Accessing Configuration
Section titled “Accessing Configuration”Use the ConfigRepositoryInterface with dot notation:
<?php
declare(strict_types=1);
use Marko\Config\ConfigRepositoryInterface;
readonly class DatabaseService{ public function __construct( private ConfigRepositoryInterface $configRepository, ) {}
public function getHost(): string { return $this->configRepository->getString('database.host'); }}Typed Accessors
Section titled “Typed Accessors”Never worry about type coercion. Every accessor enforces the return type:
| Method | Returns |
|---|---|
getString(key) | string |
getInt(key) | int |
getFloat(key) | float |
getBool(key) | bool |
getArray(key) | array |
get(key) | mixed |
All typed accessors throw if the value doesn’t match the expected type. No silent coercion.
Environment Variables
Section titled “Environment Variables”Environment variables belong in .env. They should only be referenced from config files, never directly in application code:
DB_HOST=localhostDB_PORT=5432DB_DATABASE=markoAPP_DEBUG=trueRead them with the Marko\Config\Env reader, which parses each value to the right type and fails the boot with a ConfigException when a value is invalid. See Environment Variables for every method.
use Marko\Config\Env;
return [ 'debug' => Env::bool('APP_DEBUG', false),];$debug = $this->configRepository->getBool('app.debug');This keeps environment variables in one place and makes your application testable with config overrides.
Where Config Defaults Go
Section titled “Where Config Defaults Go”Config defaults go in each module’s config/ directory. When several files provide the same config key, the later one wins: vendor modules, then modules/, then app/ modules, then your project-root config/ directory. Your own config overrides the defaults that ship with a module:
vendor/marko/cache/config/cache.php → Base defaultsmodules/acme/cache/config/cache.php → Third-party overridesapp/my-app/config/cache.php → Your module overridesconfig/cache.php → Project overrides (wins)Which Config Location to Use
Section titled “Which Config Location to Use”The four locations do two different jobs:
- A module’s
config/ships defaults with its code. The file belongs to the module and travels with it, so every project that installs the module gets the same starting values. - The project-root
config/holds settings for this installation. Database credentials, the cache or mail driver, the app URL and anything read from the environment belong to the deployment, not to any one module.
When you’re deciding where a value goes:
| You’re setting | Put it in |
|---|---|
| Defaults for a module you’re writing | That module’s config/ |
An override that belongs with one of your app modules, such as a blog’s posts_per_page | That app module’s config/ (app/blog/config/blog.php) |
| A project-wide or per-environment value, or an override of a vendor package’s config | The project-root config/ (config/cache.php) |
Most overrides belong in the project-root config/. A fresh project’s app/ is empty, and the root config/ works without creating a module just to hold settings. It is also the one place that always wins.