Download the PHP package rasuvaeff/yii3-feature-flags-db without Composer

rasuvaeff/yii3-feature-flags-db

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

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 ^2.0
• yiisoft/db-migration ^2.1 (ships the table migration)
• yiisoft/definitions ^3.0 (DI Reference for WritableFlagProvider)
• a PSR-16 cache implementation — required transitively by yiisoft/db 2.0 (e.g. yiisoft/cache)

Installation

With Yii3 config-plugin this package binds both FlagProvider and WritableFlagProvider to the same instance — do not also bind either key in your application or another backend, or yiisoft/config reports a Duplicate key error.

Database schema

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

environments deliberately carries no DEFAULT: MySQL and MariaDB reject a literal default on a TEXT column (error 1101). DbFlagProvider::save() writes every column on every upsert, so a hand-written INSERT must supply it too — the empty set is the string '' or '[]'.

Migration

Register the bundled migration by namespace — no vendor paths:

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

Custom table name

Set it in params — the same value reaches the migration and DbFlagProvider:

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.

Usage

Basic DB provider

With PSR-16 caching

Clear cache

Writing flags

DbFlagProvider and CachedFlagProvider both implement WritableFlagProvider. Use them for programmatic CRUD or an admin UI.

• save() is an upsert keyed by name (insert or replace).
• remove() is idempotent: deleting a missing name is a no-op.
• CachedFlagProvider is write-through: after a successful save()/remove() it clears its cache before returning, so the next read reflects the change. When the inner provider is read-only (e.g. ConfigFlagProvider), write calls are silent no-ops — wrap a config provider safely without exceptions.
• Salt is normalized: Flag::__construct() replaces an empty salt with the flag name. On write the row stores '' whenever salt === name so the round-trip read keeps the same invariant (emptySaltFallsBackToName).
• Environments are encoded through FlagRowMapper::encodeEnvironments() and decoded through extractEnvironments(). Round-trip is guaranteed.

Writable DI binding

config/di.php binds WritableFlagProvider to the same instance as FlagProvider via Yiisoft\Definitions\Reference:

Inject WritableFlagProvider in write paths and FlagProvider in read paths; both resolve to the same object.

API reference

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

License

BSD-3-Clause. See LICENSE.md.