Search by

nowo-tech / runtime-setting-contract

HecFranco

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

Documentation

pkg:composer/nowo-tech/runtime-setting-contract

Fund package maintenance!

HecFranco

Statistics

Installs: 163

Dependents: 1

Suggesters: 1

Stars: 0

Open Issues: 1

v1.0.0 2026-11-15 19:31 UTC

This package is auto-updated.

Last update: 2026-11-16 06:15:07 UTC


README

CI Packagist Version Packagist Downloads License PHP Symfony GitHub stars Coverage

⭐ 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+).

FrankenPHP Friendly Worker Mode

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

  • Per-setting source: env (default, today's behaviour), db, or db_then_env, chosen by the host.
  • Fail closed by default: on_error: fail_closed aborts when the source is down or holds an invalid value; fallback warns 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 explicit Unbounded opt-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/Contract runs without Symfony.
  • Ids compatible with RuntimeEnvBundle: namespace.key or 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/cache for 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

Additional documentation

Tests and coverage

  • Tests: PHPUnit under tests/Unit/ and tests/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.