FeatureFlag Dispatcher

Run code by feature flag without if blocks: register handlers, or mark methods with an attribute, and dispatch.

Feature flags are a powerful technique for managing features in your application, enabling you to toggle functionality on/off without deploying new code. This library provides a clean, interface-based approach to dispatch handlers based on feature flag states.

Why

Feature flags usually end up as if ($flags->isEnabled('x')) scattered through the code. Each new flag adds branches, and removing a flag means finding every one of them.

FeatureFlag moves the decision to one place, the dispatcher. Each handler, or each method marked with an attribute, declares the flag and value it runs for:

class NotificationService
{
    #[FeatureFlagAttribute('email-notifications', 'enabled')]
    public function sendEmail(string $to, string $subject): void { /* ... */ }

    #[FeatureFlagAttribute('sms-notifications')]
    public function sendSms(string $to, string $subject): void { /* ... */ }
}

$dispatcher->addClass(NotificationService::class);
$dispatcher->dispatch($to, $subject);   // runs only the methods whose flag matches

Turning a feature on or off is a change to the flags, not to the code that uses it.

Basic Usage

use ByJG\FeatureFlag\FeatureFlags;
use ByJG\FeatureFlag\FeatureFlagDispatcher;
use ByJG\FeatureFlag\FeatureFlagSelector;
use ByJG\FeatureFlag\FeatureFlagHandlerInterface;

// Initialize the enabled features
FeatureFlags::addFlag('flag1', 'value1');
FeatureFlags::addFlag('flag2', 'value2');
FeatureFlags::addFlag('flag3');

// Create handler implementations
class MyHandler implements FeatureFlagHandlerInterface
{
    public function execute(mixed ...$args): mixed
    {
        echo "Handler executed!\n";
        return null;
    }
}

// Create a Dispatcher
$dispatcher = new FeatureFlagDispatcher();

// Add feature flag handlers
$dispatcher->add(FeatureFlagSelector::whenFlagIs('flag2', 'value1', new MyHandler()));
$dispatcher->add(FeatureFlagSelector::whenFlagIs('flag2', 'value2', new MyHandler()));

// Dispatch the request
$dispatcher->dispatch();

// Since there is a feature flag 'flag2' with value 'value2', the corresponding handler will be executed

note

If one or more feature flags match the condition, all matching handlers will be executed in the order they were added.

Managing the Flags

FeatureFlags keeps the enabled flags in a static list shared by every dispatcher:

use ByJG\FeatureFlag\FeatureFlags;

FeatureFlags::addFlag('flag1', 'value1');              // a flag with a value
FeatureFlags::addFlag('flag3');                        // a flag with no value (null): only whenFlagIsSet() matches it
FeatureFlags::addFromContainer('flag4', $container);   // added only if the PSR-11 container has 'flag4'

FeatureFlags::hasFlag('flag1');   // true
FeatureFlags::getFlag('flag1');   // 'value1'; throws InvalidArgumentException if the flag was not added
FeatureFlags::getFlags();         // ['flag1' => 'value1', 'flag3' => null, ...]
FeatureFlags::clearFlags();       // remove every flag

Handler Types

• Handler Interface - Create custom handlers implementing FeatureFlagHandlerInterface
• Attributes - Use PHP 8 attributes to mark methods as handlers

Selector Types

• FeatureFlagSelector - Single condition selectors
• FeatureFlagSelectorSet - Multiple condition selectors (ALL must match)

Advanced Usage

• Search Order - Control the order of handler execution
• Passing Arguments - Pass runtime arguments to handlers

Installation

composer require "byjg/featureflag"

Requirements

• PHP 8.3 to 8.6
• PSR-11 Container (optional, for container integration)

Running Tests

composer test

---

Open source ByJG