league/config

The league/config library follows a simple, opinionated approach focused on strict, code-driven configuration. It is designed for scenarios where configuration is managed via PHP code rather than external files.

Core Principles:

• Array-based structure: Configuration operates on nested arrays that are easily accessible.
• Strict Schemas: The structure, allowed types, and allowed values are strictly defined.
• Fluent Interface: Schemas are defined using a simple, fluent API.
• Immutability: Schemas are immutable and cannot be modified once set. You can add or combine schemas, but you must never modify an existing one.
• Code-driven: Both configuration values and schemas are defined and managed using PHP code.
• Separation of Concerns: Configuration values must never define or influence the schemas.

What this library does NOT do:

• It does not support loading or exporting configuration via YAML, XML, or other file formats (though you can implement this yourself).
• It does not parse configuration from command lines or user interfaces.
• It does not allow dynamic schema changes (e.g., changing allowed values based on other configuration values).

By default, league/config uses lazy processing. This means that user-provided values are not processed or validated against the schema immediately upon instantiation or when using merge() or set(). Instead, validation is deferred until the first time you attempt to read or check a value.

This behavior provides flexibility, allowing you to:

1. Set values from multiple different sources sequentially.
2. Add missing required values later in the application lifecycle before they are accessed.

Note: Because validation is deferred, errors (such as missing required keys or type mismatches) will not be thrown during the configuration setup phase, but rather when you call $config->get() or similar retrieval methods.

use League\Config\Configuration;
use Nette\Schema\Expect;

$config = new Configuration([
    'debug_mode' => Expect::bool()->required(),
]);

// No validation happens here, even if 'debug_mode' is missing
$config->merge(['other_key' => 'value']);

// Validation occurs HERE. If 'debug_mode' was never set, an exception is thrown.
if ($config->get('debug_mode')) {
    // ...
}

A schema defines the structure of your configuration, including allowed keys, value types, and validation rules. league/config uses the nette/schema package for this purpose. You define schemas using the Nette\Schema\Expect class and pass them into the League\Config\Configuration constructor.

With schemas, you can:

• Mark options as required.
• Provide default values.
• Validate types (int, string, bool, etc.), ranges (min/max), regular expressions, or enums.
• Mark options as deprecated.
• Use custom assertions via assert().
• Cast values to specific types.

Note on nested structures: While nette/schema typically casts nested structures (Expect::structure) to stdClass objects, league/config automatically casts them to array for you.

use League\Config\Configuration;
use Nette\Schema\Expect;

$config = new Configuration([
    'debug_mode' => Expect::bool(),
    'database' => Expect::structure([
        'driver' => Expect::anyOf('mysql', 'postgresql', 'sqlite')->required(),
        'host' => Expect::string()->default('localhost'),
        'port' => Expect::int()->min(1)->max(65535),
        'ssl' => Expect::bool(),
        'database' => Expect::string()->required(),
        'username' => Expect::string()->required(),
        'password' => Expect::string()->nullable(),
    ]),
    'logging' => Expect::structure([
        'enabled' => Expect::bool()->default($_ENV['DEBUG'] == true),
        'file' => Expect::string()->deprecated("use logging.path instead"),
        'path' => Expect::string()->assert(function ($path) { return \is_writeable($path); })->required(),
    ]),
]);

Using league/config involves a three-step workflow to manage application settings with validation:

1. Define the configuration schema: Specify the overall structure, required options, validation constraints (using Nette\Schema\Expect), and default values.
2. Apply user-provided values: Merge external data (like arrays from config files or environment variables) into the configuration instance.
3. Read validated options: Retrieve the processed and validated values using dot-notation keys to drive application logic.

Note: This guide refers to version 1.1 patterns.

use League\Config\Configuration;
use Nette\Schema\Expect;

// 1. Define schema
$config = new Configuration([
    'database' => Expect::structure([
        'driver' => Expect::anyOf('mysql', 'postgresql', 'sqlite')->required(),
        'host' => Expect::string()->default('localhost'),
    ]),
]);

// 2. Set values
$config->merge([
    'database' => [
        'driver' => 'mysql',
    ],
]);

// 3. Read values
$driver = $config->get('database.driver');

If different components of your application define their own schemas (e.g., a DatabaseConnection class and a Logger class), you can combine them into a single League\Config\Configuration instance.

You can achieve this in three ways:

1. Passing an array of schemas to the Configuration constructor.
2. Passing some schemas to the constructor and using addSchema() for others.
3. Initializing an empty Configuration and calling addSchema() multiple times.

Each call to addSchema(string $name, Schema $schema) registers a specific sub-section of your configuration.

use League\Config\Configuration;

// Option 1: All in constructor
$config = new Configuration([
    'database' => DatabaseConnection::getSchema(),
    'logging' => Logger::getSchema(),
]);

// Option 2: Mix constructor and addSchema()
$config = new Configuration([
    'database' => DatabaseConnection::getSchema(),
]);
$config->addSchema('logging', Logger::getSchema());

// Option 3: All via addSchema()
$config = new Configuration();
$config->addSchema('database', DatabaseConnection::getSchema());
$config->addSchema('logging', Logger::getSchema());

The League\Config\Configuration class is the primary entry point. It allows you to define a strict schema using Nette\Schema\Expect and manage configuration values.

Key features:

• Schema Definition: Use Expect to define types, required fields, defaults, and custom assertions.
• Value Setting: Use merge() to set multiple values at once or set() to set a single value using dot or slash notation.
• Value Retrieval: Use get() to fetch values. Validation and defaults are applied automatically.
• Existence Checking: Use exists() to check for a key without triggering an exception.
• Error Handling: If validation fails or a non-existent key is requested via get(), an InvalidConfigurationException is thrown.

use League\Config\Configuration;
use Nette\Schema\Expect;

// 1. Define your configuration schema
$config = new Configuration([
    'database' => Expect::structure([
        'driver' => Expect::anyOf('mysql', 'postgresql', 'sqlite')->required(),
        'host' => Expect::string()->default('localhost'),
        'port' => Expect::int()->min(1)->max(65535),
        'ssl' => Expect::bool(),
        'database' => Expect::string()->required(),
        'username' => Expect::string()->required(),
        'password' => Expect::string()->nullable(),
    ]),
    'logging' => Expect::structure([
        'enabled' => Expect::bool()->default($_ENV['DEBUG'] == true),
        'file' => Expect::string()->deprecated("use logging.path instead"),
        'path' => Expect::string()->assert(function ($path) { return \is_writeable($path); })->required(),
    ]),
]);

// 2. Set values
$config->merge([
    'database' => [
        'driver' => 'mysql',
        'port' => 3306,
        'database' => 'mydb',
        'username' => 'user',
        'password' => 'secret',
    ],
]);
$config->set('logging.path', '/var/log/myapp.log');

// 3. Retrieve values
$config->get('database');        // Returns entire section as array
$config->get('database.driver'); // Returns specific value via dot notation
$config->get('database/driver'); // Returns specific value via slash notation
$config->get('database.host');   // Returns default value "localhost"

// 4. Check existence
if ($config->exists('foo.bar')) {
    // ...
}