rasuvaeff/yii3-settings

Typed runtime settings for Yii3 applications

v1.0.0 2026-06-05 17:25 UTC

Requires

• php: ^8.3
• psr/simple-cache: ^3.0

Requires (Dev)

• ergebnis/composer-normalize: ^2.51
• friendsofphp/php-cs-fixer: ^3.95
• infection/infection: ^0.29
• maglnet/composer-require-checker: ^4.17
• phpunit/phpunit: ^11.5
• psalm/plugin-phpunit: ^0.19
• rector/rector: ^2.4
• vimeo/psalm: ^6.16

BSD-3-Clause

• Victor Razuvaev

• configuration
• Settings
• yii3

README

Typed runtime settings for Yii3: typed getters, multiple providers, cache decorator.

Using an AI coding assistant? llms.txt has a compact API reference you can give to the LLM to help it work with this package.

Requirements

• PHP 8.3+
• psr/simple-cache ^3.0

Installation

composer require rasuvaeff/yii3-settings

Usage

Typed getters

use Rasuvaeff\Yii3Settings\Settings;

$currency = $settings->string(key: 'billing.currency');
$limit = $settings->int(key: 'orders.max_items');
$enabled = $settings->bool(key: 'mail.enabled');
$features = $settings->array(key: 'app.features');

Setting keys and values

use Rasuvaeff\Yii3Settings\SettingKey;
use Rasuvaeff\Yii3Settings\SettingType;
use Rasuvaeff\Yii3Settings\SettingValue;

$key = new SettingKey('billing.currency');
$value = SettingValue::fromRaw(type: SettingType::String, value: 'USD');

Configuration

return [
    'rasuvaeff/yii3-settings' => [
        'definitions' => [
            'billing.currency' => ['type' => 'string', 'default' => 'USD'],
            'orders.max_items' => ['type' => 'int', 'default' => 100],
            'mail.enabled' => ['type' => 'bool', 'default' => true],
        ],
    ],
];

Providers

Provider	Description
ConfigSettingsProvider	Reads from PHP config arrays
EnvSettingsProvider	Reads from environment variables
ChainSettingsProvider	Chains multiple providers (first match wins)
CachedSettingsProvider	PSR-16 cache decorator

Chain providers

$chain = new ChainSettingsProvider(providers: [
    $envProvider,
    $configProvider,
]);

Cache decorator

$cached = new CachedSettingsProvider(
    inner: $chain,
    cache: $psr16Cache,
    definitions: $definitions,
    ttl: 60,
    cacheNamespace: 'yii3-settings',
    cacheVersion: 1,
);

Strict mode

Unknown settings return type defaults in non-strict mode. Enable strict mode to throw:

$settings = new Settings(
    provider: $provider,
    definitions: $definitions,
    strictMode: true,
);

Type safety

Calling a getter with a wrong type throws SettingTypeMismatchException:

// Definition: billing.currency = string
$settings->int('billing.currency'); // throws

Public API

Class	Description
Settings	Facade: string(), int(), float(), bool(), array(), has()
SettingDefinition	Typed setting definition with key, type, default, cast
SettingKey	Validated setting key value object
SettingValue	Typed normalized setting value
SettingType	Enum: string, int, float, bool, array
SettingsProvider	Read-only provider interface
WritableSettingsProvider	Read-write provider interface
ConfigSettingsProvider	Provider from config arrays
EnvSettingsProvider	Provider from env variables
ChainSettingsProvider	Provider chain (first match wins)
CachedSettingsProvider	PSR-16 cache decorator

Security

• Setting keys are validated against /^[a-z][a-z0-9_.-]*$/.
• Type coercion is centralized in SettingDefinition::cast().
• Type mismatches throw SettingTypeMismatchException; getters do not return raw untyped values.
• Cache failures in CachedSettingsProvider are treated as cache misses and do not bypass type checks.
• Cache keys include namespace and version: yii3-settings:v1:<key>.

Examples

See examples/ for runnable scripts.

Development

make install && make build

License

BSD-3-Clause. See LICENSE.md.