ez-php/feature-flags

Simple feature flag evaluation for the ez-php framework — File, Database, and Array drivers with a static Flag facade

1.11.1 2026-05-11 20:59 UTC

Requires

• php: ^8.5
• ez-php/contracts: ^1.0

Requires (Dev)

• ez-php/docker: ^1.0
• friendsofphp/php-cs-fixer: ^3.94
• phpstan/phpstan: ^2.1
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-strict-rules: ^2.0
• phpunit/phpunit: ^13.0

MIT

• Andreas Uretschnig

• framework
• php
• flags
• rollout
• feature-flags
• feature-toggles
• ez-php

README

Simple feature flag evaluation for the ez-php framework. No external service required — flags are stored in a PHP file, a database table, or a plain array.

Installation

composer require ez-php/feature-flags

Register the provider in provider/modules.php:

\EzPhp\FeatureFlags\FeatureFlagServiceProvider::class,

Usage

use EzPhp\FeatureFlags\Flag;

if (Flag::enabled('new-checkout')) {
    // show new checkout flow
}

if (Flag::disabled('dark-mode')) {
    // show light theme
}

// Context-aware evaluation (e.g. per-user gradual rollouts)
if (Flag::enabledFor('beta-search', $user->id)) {
    // show beta search to this user
}

if (Flag::disabledFor('new-ui', $user->id)) {
    // show legacy UI for this user
}

$all = Flag::all(); // ['new-checkout' => true, 'dark-mode' => false]

Configuration

Add a config/flags.php to your application:

return [
    'flags' => [
        'driver' => env('FLAGS_DRIVER', 'file'),  // file | database | array
        'file'   => base_path('config/flags.php'),
    ],
];

Drivers

Driver	Config key value	Description
file	file	Reads a PHP file returning array<string, bool>
database	database	Reads a feature_flags table via PDO
array	array	Empty in-memory driver (CI / test environments)

File driver

Create config/flags.php in your application:

<?php

return [
    'new-checkout' => true,
    'dark-mode'    => false,
    'beta-search'  => false,
];

Database driver

Create the feature_flags table (example migration):

$pdo->exec('
    CREATE TABLE feature_flags (
        name    VARCHAR(255) NOT NULL PRIMARY KEY,
        enabled TINYINT(1)   NOT NULL DEFAULT 0
    )
');

For per-context overrides (e.g. per-user beta rollouts), also create feature_flag_contexts:

$pdo->exec('
    CREATE TABLE feature_flag_contexts (
        name       VARCHAR(255) NOT NULL,
        context_id VARCHAR(255) NOT NULL,
        enabled    TINYINT(1)   NOT NULL DEFAULT 0,
        PRIMARY KEY (name, context_id)
    )
');

When enabledFor('flag', $userId) is called, the driver checks feature_flag_contexts first; if no matching row exists, it falls back to the global feature_flags value. A missing feature_flag_contexts table is silently treated as "no overrides" — no migration is required for basic use.

Insert flags directly via SQL or through your own admin interface:

INSERT INTO feature_flags (name, enabled) VALUES ('new-checkout', 1);
INSERT INTO feature_flag_contexts (name, context_id, enabled) VALUES ('beta-search', '42', 1);

Behaviour

• Unknown flags default to false — Flag::enabled('unknown') never throws.
• Drivers never throw — all query/file failures are caught internally and result in false.
• The Flag facade throws RuntimeException when called before FeatureFlagServiceProvider has been booted — this is a programmer error, not a runtime failure.

Testing

docker compose exec app composer test

All tests run without external infrastructure (SQLite :memory: for the database driver, temp files for the file driver).

License

MIT