Download the PHP package rasuvaeff/yii3-settings-db without Composer

rasuvaeff/yii3-settings-db

Русская версия

Database-backed writable settings provider for Yii3 applications. Implements WritableSettingsProvider and SettingsInspector from rasuvaeff/yii3-settings, persists runtime overrides in a DB table, and supports at-rest encryption of secret settings via libsodium (XChaCha20-Poly1305).

Using an AI coding assistant? llms.txt has a compact API reference you can feed into the model.

Requirements

• PHP 8.3+
• ext-sodium (bundled with PHP 7.2+)
• rasuvaeff/yii3-settings ^1.0
• yiisoft/db ^2.0
• yiisoft/db-migration ^2.0
• a PSR-16 cache implementation — required transitively by yiisoft/db 2.0 (e.g. yiisoft/cache)

Installation

Requires rasuvaeff/yii3-settings ^1.0. With Yii3 config-plugin this package binds SettingsProvider, WritableSettingsProvider and SettingsInspector automatically (all resolve to the same DbSettingsProvider instance); the core binds the Settings facade. Do not also bind these in your application or another backend, or yiisoft/config reports a Duplicate key error.

Usage

Basic provider

The constructor accepts an optional fallback (SettingsProvider). When a key has no stored DB row, get() delegates to the fallback (which must recognize the same keys) instead of returning the definition default — this is how config values are preserved in the DI wiring below. Without a fallback, a missing row resolves to SettingDefinition::default.

Yii3 config-plugin wiring

The package ships config/params.php and config/di.php via config-plugin. It binds WritableSettingsProvider, SettingsProvider and SettingsInspector; the Settings facade itself is bound by the core (rasuvaeff/yii3-settings ^1.0) from the injected SettingsProvider. The default wiring keeps explicit config values working: DbSettingsProvider is built with a ConfigSettingsProvider fallback, so a key without a stored DB row resolves to its config value (and only then to the definition default).

Encryption is turnkey: set rasuvaeff/yii3-settings-db.cipher.key (a 32-byte key, base64) and the wiring builds the KeyRing + SodiumCipher for you — no manual crypto wiring in the host app. When any secret definition exists, the key is required (the provider throws at construction otherwise).

Runtime precedence after wiring:

Migration

Register the bundled migration by namespace — no vendor paths:

yiisoft/db-migration resolves the migration through Injector::make(), so it picks up the table-name value object from the container the same way the provider does — no manual wiring needed beyond setSourceNamespaces() above.

Set the table name in params — the same value reaches the migration and DbSettingsProvider:

Do not configure the migration through the DI container. M...::class => ['__construct()' => ['table' => ...]] does not work: the migration is built by Injector::make(), which resolves arguments by type and never reads a container definition keyed by the migration's own class. Worse, adding that definition makes the container fatal at build time in every request, because the class is not autoloadable until the migration runner requires it. That recipe was documented in 1.x; it never worked.

Core cache decorator

Secret settings

Settings inspector

Key rotation

Bulk operations

getByPrefix() runs a single LIKE query, then resolves each key through the normal precedence (DB row > fallback > default). setMany() validates all keys upfront (unknown → UnknownSettingException, readonly → ReadonlySettingException), then upserts in a transaction — if any write fails the entire batch rolls back.

Console commands

The settings:reencrypt command runs reencryptSecrets() on the active DbSettingsProvider instance. Works in any Symfony Console / yiisoft/yii-console application. The ReencryptSettingsCommand class is autowired via DI.

Public API

Security

• Unknown keys are rejected: get(), set(), and remove() throw UnknownSettingException.
• DB values are normalized through SettingDefinition; malformed ints/floats/arrays throw InvalidSettingRowException.
• User values go through bound parameters in write/delete commands.
• Table names must be trusted application configuration.
• At-rest encryption: XChaCha20-Poly1305 AEAD via libsodium. Each value uses a random 24-byte nonce.
• AAD binding: ciphertext is bound to the setting key — a value cannot be moved to a different row.
• Fail loud: tampered data throws DecryptionException, never silent fallback.
• Key rotation: keyId in envelope allows reading with old key, writing with active key.
• Secret values do not appear in SettingState::effectiveValue (masked as null).
• Cipher is required when secret: true definitions exist — fail-fast at construction.

Examples

See examples/ for runnable scripts.

Development

License

BSD-3-Clause. See LICENSE.md.