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

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