layout: default title: Schemas description: Defining the structure of your configurations, along with validation, default values, and more

Configuration Schemas

A "schema" defines the exact structure of arrays, keys, and values that users can configure. By using a schema, you can:

• Enforce that certain expected options are set by marking them required
• Provide default values when none are provided by the user
• Validate that values are certain types, numbers within ranges, match regular expressions, or contain specific sets of values (like enums)
• Mark old options as deprecated
• Cast values to certain types, including both scalars and custom objects

This library includes the nette/schema package to define and process the schemas. You use their Expect class to define the schemas, passing those into our library which handles all of the processing for you. You can find some example of that below, but we highly recommending reading their documentation for complete details on all the options available to you.

Example

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

// Define your configuration schema
$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(),
    ]),
]);

Tip: By default, nette/schema assumes that nested options (Expect::structure) will be cast to stdClass objects, but we automatically cast those to array instead, so don't worry about doing that yourself.

Merging Schemas

You might have different systems or components that define their own schemas:

use Nette\Schema\Expect;use Nette\Schema\Schema;

class DatabaseConnection
{
    public static function getSchema(): Schema
    {
        return 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(),
        ]);
    }
}

class Logger
{
    public static function getSchema(): Schema
    {
        return 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(),
        ]);
    }
}

You can combine these into a single Configuration using the constructor and/or the addSchema() method. All three examples in the snippet below will achieve the same result:

use League\Config\Configuration;

$config = new Configuration([
    'database' => DatabaseConnection::getSchema(),
    'logging' => Logger::getSchema(),
]);

// or

$config = new Configuration([
    'database' => DatabaseConnection::getSchema(),
]);

$config->addSchema('logging', Logger::getSchema());

// or

$config = new Configuration();
$config->addSchema('database', DatabaseConnection::getSchema());
$config->addSchema('logging', Logger::getSchema());

Schema Types

See the nette/schema documentation for full details on the different Expect options you can use to define different types of schemas.