rasuvaeff/yii3-feature-flags-db

Database-backed feature flag provider for Yii3 applications

v1.0.0 2026-06-05 14:31 UTC

Requires

• php: ^8.3
• psr/simple-cache: ^3.0
• rasuvaeff/yii3-feature-flags: ^1.0
• yiisoft/db: ^1.2
• yiisoft/db-migration: ^1.2

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
• yiisoft/db-sqlite: ^1.2

BSD-3-Clause

• Victor Razuvaev

• database
• db
• provider
• feature-flags
• yii3

README

Database-backed feature flag provider for Yii3 applications. Implements the FlagProvider interface from rasuvaeff/yii3-feature-flags and reads flag configuration from a database table in a single query.

Using an AI coding assistant? llms.txt contains a compact API reference you can ingest in your prompt context.

Requirements

• PHP 8.3+
• rasuvaeff/yii3-feature-flags ^1.0
• yiisoft/db ^1.2
• yiisoft/db-migration ^1.2 (ships the table migration)

Installation

composer require rasuvaeff/yii3-feature-flags-db

Database schema

Create the feature_flags table (adjust types for your RDBMS):

CREATE TABLE feature_flags (
    name        VARCHAR(190) PRIMARY KEY,
    enabled     BOOLEAN      NOT NULL DEFAULT TRUE,
    salt        VARCHAR(190) NOT NULL DEFAULT '',
    rollout     SMALLINT     NOT NULL DEFAULT 100,
    kill_switch BOOLEAN      NOT NULL DEFAULT FALSE,
    environments TEXT        NOT NULL DEFAULT '[]'
);

Column	Type	Default	Description
name	VARCHAR(190) PK	—	Flag name (core regex: /^[a-z][a-z0-9._-]*$/)
enabled	BOOLEAN	true	Whether the flag is active
salt	VARCHAR(190)	''	Empty string falls back to flag name
rollout	SMALLINT	100	Percentage 0..100
kill_switch	BOOLEAN	false	Emergency off switch
environments	JSON/TEXT	'[]'	JSON array of strings

Migration

The package ships a migration (migrations/) for yiisoft/db-migration. Register the source path in your app's config/params.php:

'yiisoft/db-migration' => [
    'sourcePaths' => [
        dirname(__DIR__) . '/vendor/rasuvaeff/yii3-feature-flags-db/migrations',
    ],
],

Then apply and revert it with Yii Console:

./yii migrate:up
./yii migrate:down --limit=1

The table name defaults to feature_flags and must match the table argument of DbFlagProvider. To use a custom name, bind the migration constructor argument:

M260605000000CreateFeatureFlagsTable::class => [
    '__construct()' => ['table' => 'my_feature_flags'],
],

Usage

Basic DB provider

use Rasuvaeff\Yii3FeatureFlags\FeatureFlags;
use Rasuvaeff\Yii3FeatureFlagsDb\DbFlagProvider;

$provider = new DbFlagProvider(
    db: $connection,          // yiisoft/db ConnectionInterface
    table: 'feature_flags',   // optional, default is 'feature_flags'
);

$featureFlags = new FeatureFlags(provider: $provider);

if ($featureFlags->isEnabled('new-checkout')) {
    // new checkout flow
}

With PSR-16 caching

use Rasuvaeff\Yii3FeatureFlagsDb\CachedFlagProvider;

$cached = new CachedFlagProvider(
    inner: $provider,
    cache: $psr16Cache,       // PSR-16 CacheInterface
    ttl: 60,                  // seconds
);

$featureFlags = new FeatureFlags(provider: $cached);

Clear cache

$cached->clear();             // removes cached flags, next call reloads from DB

API reference

Class	Description
DbFlagProvider	Reads all flags from DB in one SELECT *
CachedFlagProvider	PSR-16 decorator, caches entire flag set with TTL
InvalidFlagRowException	Thrown when a DB row has invalid structure

Security

• Kill switch, rollout hash logic, and environment targeting remain in the core package — the DB adapter is only a configuration source.
• Invalid row data (missing columns, malformed JSON, wrong types, out-of-range rollout, invalid flag name) throws InvalidFlagRowException instead of silently enabling features. Core validation errors are wrapped, so callers only need to catch InvalidFlagRowException.
• No SQL injection risk: table name is quoted via yiisoft/db quoter.

Examples

See examples/ for runnable scripts.

Development

composer build          # full gate: validate + normalize + cs + psalm + test
composer cs:fix         # auto-fix code style
composer psalm          # static analysis
composer test           # run tests

License

BSD-3-Clause. See LICENSE.md.