PHPackages rasuvaeff/yii3-settings - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. rasuvaeff/yii3-settings ActiveLibrary[Utility & Helpers](/categories/utility) rasuvaeff/yii3-settings ======================= Typed runtime settings for Yii3 applications v1.1.2(3w ago)0300↑220%2BSD-3-ClausePHPPHP 8.3 - 8.5CI passing Since Jun 13Pushed 1w agoCompare [ Source](https://github.com/rasuvaeff/yii3-settings)[ Packagist](https://packagist.org/packages/rasuvaeff/yii3-settings)[ Docs](https://github.com/rasuvaeff/yii3-settings)[ RSS](/packages/rasuvaeff-yii3-settings/feed)WikiDiscussions master Synced 1w ago READMEChangelogDependencies (20)Versions (5)Used By (2) rasuvaeff/yii3-settings ======================= [](#rasuvaeffyii3-settings) [![Stable Version](https://camo.githubusercontent.com/0714d782fa91a917c2446ffd0f56293df29076cd51c3b665483b0ad2ed555a01/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7261737576616566662f796969332d73657474696e67732e7376673f6c6162656c3d737461626c65)](https://packagist.org/packages/rasuvaeff/yii3-settings)[![Total Downloads](https://camo.githubusercontent.com/f850fce15e67264f179e16ae81be3842504fc5a2358255e19d442b31afc5cfa1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7261737576616566662f796969332d73657474696e67732e737667)](https://packagist.org/packages/rasuvaeff/yii3-settings)[![Build](https://camo.githubusercontent.com/c77e97888cbf353d0aae47962af66b5e181aeb5d177e770502d62cb2a78b5c20/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7261737576616566662f796969332d73657474696e67732f6275696c642e796d6c3f6272616e63683d6d6173746572)](https://github.com/rasuvaeff/yii3-settings/actions)[![Static Analysis](https://camo.githubusercontent.com/e51869a764b6cbf42a3553fe6a5f4ce77f0a2350b709c69813bfc533e388fe9d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7261737576616566662f796969332d73657474696e67732f7374617469632d616e616c797369732e796d6c3f6272616e63683d6d6173746572266c6162656c3d7073616c6d)](https://github.com/rasuvaeff/yii3-settings/actions)[![PHP](https://camo.githubusercontent.com/57caef6f328a744d2af9e6ff2cbe5ba9a0ba563b7c411a1a8e9dd8855d43816d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f7261737576616566662f796969332d73657474696e67732f706870)](https://packagist.org/packages/rasuvaeff/yii3-settings)[![License](https://camo.githubusercontent.com/f33dd4a7614341f0968a34cccd5a3060191a006e23ce42a63dc915752838ccc0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7261737576616566662f796969332d73657474696e67732e737667)](LICENSE.md)[Русская версия](README.ru.md) Typed runtime settings for Yii3: typed getters, multiple providers, cache decorator, encryption contract, inspector. > Using an AI coding assistant? [llms.txt](llms.txt) has a compact API reference you can give to the LLM to help it work with this package. Requirements ------------ [](#requirements) - PHP 8.3+ - `psr/simple-cache` ^3.0 Installation ------------ [](#installation) ``` composer require rasuvaeff/yii3-settings ``` Usage ----- [](#usage) ### Typed getters [](#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 [](#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 [](#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], ], ], ]; ``` ### Provider wiring (Yii3 config-plugin) [](#provider-wiring-yii3-config-plugin) The core wires only the `Settings` facade. The `SettingsProvider` implementation is supplied by **exactly one** source — a storage backend or, for config-array settings, the application. This keeps backends drop-in (install one and it is wired automatically) with no `Duplicate key` config conflict. SetupHow `SettingsProvider` is boundDatabase-backedinstall [`rasuvaeff/yii3-settings-db`](https://github.com/rasuvaeff/yii3-settings-db) — it binds it automaticallyConfig-onlybind it once in your app config (snippet below)For a config-only setup, bind `SettingsProvider` to `ConfigSettingsProvider` in `config/common/di/*.php`: ``` use Rasuvaeff\Yii3Settings\ConfigSettingsProvider; use Rasuvaeff\Yii3Settings\SettingsProvider; /** @var array $params */ return [ SettingsProvider::class => [ 'class' => ConfigSettingsProvider::class, '__construct()' => [ 'definitions' => $params['rasuvaeff/yii3-settings']['definitions'], 'values' => $params['rasuvaeff/yii3-settings']['values'], ], ], ]; ``` Bind `SettingsProvider` from a single source — a backend plus a manual binding reintroduces the `Duplicate key` conflict. ### Providers [](#providers) ProviderDescription`ConfigSettingsProvider`Reads from PHP config arrays`EnvSettingsProvider`Reads from environment variables`ChainSettingsProvider`Chains multiple providers (first match wins)`CachedSettingsProvider`PSR-16 cache decorator (write-through since 1.1.0)### Chain providers [](#chain-providers) ``` $chain = new ChainSettingsProvider(providers: [ $envProvider, $configProvider, ]); ``` ### Cache decorator [](#cache-decorator) `CachedSettingsProvider` is a PSR-16 read cache. Since 1.1.0 it is also **write-through**: when the inner provider implements `WritableSettingsProvider`, `set()`/`remove()` delegate to it and invalidate the cached entry for the key — so reads never observe a stale value after a write. Bind it as the single `WritableSettingsProvider`/`SettingsProvider` and the cache stays coherent automatically. ``` $cached = new CachedSettingsProvider( inner: $writableProvider, // write-through: writes delegate + clear the cache key cache: $psr16Cache, definitions: $definitions, ttl: 60, cacheNamespace: 'yii3-settings', cacheVersion: 1, ); ``` ### Strict mode [](#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 [](#type-safety) Calling a getter with a wrong type throws `SettingTypeMismatchException`: ``` // Definition: billing.currency = string $settings->int('billing.currency'); // throws ``` Public API ---------- [](#public-api) ClassDescription`Settings`Facade: `string()`, `int()`, `float()`, `bool()`, `array()`, `has()``SettingDefinition`Typed setting definition: key, type, default, cast, secret flag, and optional presentation/policy metadata (`label`, `group`, `help`, `choices`, `readonly`)`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`SettingsInspector`Admin-facing read-model: `describe()` returns `SettingState``SettingState`Value object: key, value, source, stored override, secret, writable`ConfigSettingsProvider`Provider from config arrays`EnvSettingsProvider`Provider from environment variables`ChainSettingsProvider`Provider chain (first match wins)`CachedSettingsProvider`PSR-16 cache decorator (write-through since 1.1.0)`Cipher`Encryption interface (AEAD with associated data)`DecryptionException`Decryption failure (tampered data)`UnknownEncryptionKeyException`Key ID in envelope not found in KeyRing### Secret settings [](#secret-settings) ``` $def = new SettingDefinition( key: 'billing.stripe_key', type: SettingType::String, secret: true, ); ``` From config: ``` 'billing.stripe_key' => ['type' => 'string', 'secret' => true], ``` ### Presentation & policy metadata [](#presentation--policy-metadata) A definition can carry optional UI/policy hints used by admin tooling (e.g. `rasuvaeff/yii3-settings-ui`). They are inert for the core providers, except `readonly`, which writable providers reject and `describe()` reflects via `SettingState::isWritable`. ``` $def = new SettingDefinition( key: 'orders.status', type: SettingType::String, default: 'new', label: 'Default order status', group: 'Orders', help: 'Status assigned to freshly created orders', choices: ['new', 'paid', 'shipped'], readonly: false, ); ``` From config: ``` 'orders.status' => [ 'type' => 'string', 'default' => 'new', 'label' => 'Default order status', 'group' => 'Orders', 'help' => 'Status assigned to freshly created orders', 'choices' => ['new', 'paid', 'shipped'], 'readonly' => false, ], ``` RuleDetail`secret=true`Only allowed for `SettingType::String``secret=false`Default — existing definitions unchanged### Encryption contract [](#encryption-contract) ``` use Rasuvaeff\Yii3Settings\Crypto\Cipher; // Implementations encrypt/decrypt with AAD binding to the setting key $ciphertext = $cipher->encrypt(plaintext: 'sk_live_xxx', aad: 'billing.stripe_key'); $plaintext = $cipher->decrypt(ciphertext: $ciphertext, aad: 'billing.stripe_key'); ``` ### SettingsInspector [](#settingsinspector) ``` use Rasuvaeff\Yii3Settings\SettingsInspector; $state = $inspector->describe(key: 'billing.currency'); $state->key; // 'billing.currency' $state->effectiveValue; // 'USD' (or null for masked secrets) $state->hasStoredOverride; // true $state->source; // 'db', 'config', or 'default' $state->isSecret; // false $state->isWritable; // true (false for readonly definitions) $states = $inspector->describeAll(); // list for every declared key ``` Security -------- [](#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:`. - `secret=true` is only allowed for `SettingType::String` — enforced at construction. - Secret plaintext must never be logged or included in exception messages (enforced by implementations). Examples -------- [](#examples) See [examples/](examples/) for runnable scripts. Development ----------- [](#development) ``` make install && make build ``` License ------- [](#license) BSD-3-Clause. See [LICENSE.md](LICENSE.md). ### Health Score 47 — FairBetter than 93% of packages Maintenance97 Actively maintained with recent releases Popularity17 Limited adoption so far Community11 Small or concentrated contributor base Maturity54 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~5 days Total 4 Last Release 24d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/b0812d5572a7041dfe36e222d295b2e6dc55833a605350fcde58a51a5965ed30?d=identicon)[rasuvaeff](/maintainers/rasuvaeff) --- Top Contributors [![rasuvaeff](https://avatars.githubusercontent.com/u/1352718?v=4)](https://github.com/rasuvaeff "rasuvaeff (25 commits)") --- Tags configurationphppsr-16settingstypedyii3configurationSettingsyii3 ### Code Quality TestsPHPUnit Static AnalysisPsalm, Rector Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/rasuvaeff-yii3-settings/health.svg) ``` [![Health](https://phpackages.com/badges/rasuvaeff-yii3-settings/health.svg)](https://phpackages.com/packages/rasuvaeff-yii3-settings) ``` ### Alternatives [illuminate/contracts The Illuminate Contracts package. 706130.3M14.1k](/packages/illuminate-contracts)[civicrm/civicrm-core Open source constituent relationship management for non-profits, NGOs and advocacy organizations. 751291.4k46](/packages/civicrm-civicrm-core)[flow-php/etl PHP ETL - Extract Transform Load - Abstraction 378604.0k107](/packages/flow-php-etl)[chillerlan/php-settings-container A container class for immutable settings objects. Not a DI container. 3535.1M23](/packages/chillerlan-php-settings-container)[dmishh/settings-bundle Database centric Symfony configuration management. Global and per-user settings supported. 115257.8k1](/packages/dmishh-settings-bundle)[jbtronics/settings-bundle A symfony bundle to easily create typesafe, user-configurable settings for symfony applications 9576.1k3](/packages/jbtronics-settings-bundle) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)