nowo-tech / runtime-setting-contract
Runtime setting port: a bundle setting that lives in .env can come from the database instead, change live through a console command and rotate without downtime. Framework-free contract, versioned cache, FrankenPHP worker safe, optional Symfony bridge.
Package info
github.com/nowo-tech/runtime-setting-contract
pkg:composer/nowo-tech/runtime-setting-contract
Fund package maintenance!
Requires
- php: >=8.2 <8.6
- psr/clock: ^1.0
- psr/event-dispatcher: ^1.0
- psr/log: ^2.0 || ^3.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.64
- igor-php/igor-php: ^0.10.0
- nowo-tech/phpstan-frankenphp: ^1.0
- phpstan/extension-installer: ^1.4
- phpstan/phpstan: ^2.0
- phpstan/phpstan-phpunit: ^2.0
- phpunit/phpunit: ^11.0
- psr/cache: ^2.0 || ^3.0
- rector/rector: ^2.0
- symfony/cache: ^7.4 || ^8.0
- symfony/config: ^7.4 || ^8.0
- symfony/console: ^7.4 || ^8.0
- symfony/dependency-injection: ^7.4 || ^8.0
- symfony/event-dispatcher: ^7.4 || ^8.0
- symfony/framework-bundle: ^7.4 || ^8.0
- symfony/http-kernel: ^7.4 || ^8.0
- symfony/messenger: ^7.4 || ^8.0
- symfony/process: ^7.4 || ^8.0
Suggests
- nowo-tech/instance-settings-bundle: Database source and writer in admin settings sections
- nowo-tech/runtime-env-bundle: Database source and writer: one encrypted table keyed by environment variable name
- psr/cache: For Psr6RuntimeValueCache (shared cache of non-secret values)
- symfony/console: For the nowo:runtime-setting:* commands; ^7.4 || ^8.0
- symfony/http-kernel: For the Symfony bridge (NowoRuntimeSettingBundle, boundary listener); ^7.4 || ^8.0
- symfony/messenger: The boundary listener also clears the memo between Messenger messages
Provides
None
Conflicts
- symfony/config: <7.4
- symfony/console: <7.4
- symfony/dependency-injection: <7.4
- symfony/http-kernel: <7.4
- symfony/messenger: <7.4
Replaces
None
This package is auto-updated.
Last update: 2026-11-16 06:15:07 UTC
README
⭐ Found this useful? Install it from Packagist and star runtime-setting-contract.
A bundle setting that lives in .env today can come from the database instead, change live through a console
command (or an admin UI), and rotate without downtime. This package is the contract every bundle and backend
shares: a framework-free port and resolver (PHP and PSR interfaces only), a versioned cache that reaches every worker
within version_ttl without a restart, one set of write rules, and an optional Symfony bridge.
The contract has no Symfony or Doctrine dependency. The bridge supports Symfony 7.4, 8.0 and 8.1. PHP 8.2+ (Symfony 8.x requires PHP 8.4+).
This bundle is FrankenPHP worker mode friendly, including when reset_kernel is false: one value per request,
memo cleared at every boundary, bounded state. See FrankenPHP worker audit.
Table of contents
- Features
- Installation
- Requirements
- Quick start
- Configuration
- Console commands
- Documentation
- Tests and coverage
- License
Features
- Per-setting source:
env(default, today's behaviour),db, ordb_then_env, chosen by the host. - Fail closed by default:
on_error: fail_closedaborts when the source is down or holds an invalid value;fallbackwarns and uses the env value. - Validation everywhere: the bundle's validator runs on env, database, cached and command values; values are bounded before parsing.
- Live change without restart: a per-namespace version token, read at most once per request and reused for at
most
version_ttl, invalidates an optional shared PSR-6 cache; no shared Redis needed. - Secrets: never in the shared cache, never logged or printed, only through
--stdin; no fingerprint of a secret is ever produced (audit entries record only that it changed). - Bounds are a decision: a setting that can be written at runtime needs a validator (
IntRange,SingleLineString, your own) or the explicitUnboundedopt-out, else the container build fails. - Rotation: current + previous with an expiry;
candidates()accepts both inside the window. - Worker-safe and DDD-friendly: memo cleared at every boundary;
src/Contractruns without Symfony. - Ids compatible with RuntimeEnvBundle:
namespace.keyor an environment variable name.
Installation
composer require nowo-tech/runtime-setting-contract
Symfony hosts register Nowo\RuntimeSettingContract\Bridge\Symfony\NowoRuntimeSettingBundle. See
Installation.
Requirements
- PHP >= 8.2, < 8.6
psr/clock,psr/log,psr/event-dispatcher(interfaces)- Optional: Symfony 7.4 or 8.x for the bridge,
psr/cachefor the shared cache
Quick start
use Nowo\RuntimeSettingContract\Contract\RuntimeSettingDefinition; use Nowo\RuntimeSettingContract\Contract\RuntimeSettingSource; use Nowo\RuntimeSettingContract\Contract\RuntimeSettingType; use Nowo\RuntimeSettingContract\Contract\Validator\IntRange; $retention = new RuntimeSettingDefinition( 'CHAT_RETENTION_DAYS', // or 'chat.retention_days' RuntimeSettingType::Int, RuntimeSettingSource::DbThenEnv, validator: new IntRange(1, 36500), // required when the source can be written (or Unbounded explicitly) configured: $_ENV['CHAT_RETENTION_DAYS'] ?? null, default: 90, ); $days = $resolver->get($retention); // stored value, else env, else default; validated
Configuration
nowo_runtime_setting: source: App\Settings\SettingsStore writer: App\Settings\SettingsStore cache_pool: cache.app version_ttl: 5 command: enabled: false nowo_chat_kit: retention_days: '%env(int:CHAT_RETENTION_DAYS)%' runtime: retention_days: { source: db_then_env, key: CHAT_RETENTION_DAYS, on_error: fail_closed }
Full reference: Configuration.
Console commands
Registered only with command.enabled: true:
bin/console nowo:runtime-setting:list [--namespace=chat] bin/console nowo:runtime-setting:get <id> bin/console nowo:runtime-setting:set <id> [<value>] [--stdin] [--dry-run] bin/console nowo:runtime-setting:unset <id> [--dry-run] bin/console nowo:runtime-setting:rotate <id> --stdin [--keep-previous=PT1H] [--dry-run] bin/console nowo:runtime-setting:purge # delete expired previous values at rest (schedule it)
Documentation
- Installation
- Configuration
- Usage
- Contributing
- Code of Conduct
- Changelog
- Upgrading
- Release
- Security
- Engram
- Spec-driven development
- GitHub Spec Kit
Additional documentation
- FrankenPHP worker audit (
resetKernel=false) - GitHub Actions CI requirements
- PSR evaluation (REQ-CS-007)
Tests and coverage
- Tests: PHPUnit under
tests/Unit/andtests/Integration/(Symfony kernel kept alive without the services resetter, a second PHP process running the console command, 2,000-request memory test, DDD host without Symfony, rollback visibility) - Coverage:
- PHP: 100%
- TS/JS: N/A
- Python: N/A
- Badge / CI: PHPUnit coverage job on PHP 8.2 + Symfony 7.4
License
MIT. See LICENSE.
