README

Octarine Feature Flags

Lightweight, SOLID feature flag package for PHP 8.1+.

Octarine focuses on clean boundaries and extensibility:

• Contracts define small, focused responsibilities
• Strategies are pluggable and open for extension
• Evaluator composes repository and strategies via dependency inversion

Install

Add to your Composer project (package name placeholder until published):

composer require octarine/feature-flags

Quick Start

use Octarine\Evaluator\FlagEvaluator;
use Octarine\Model\Context;
use Octarine\Model\Flag;
use Octarine\Registry\StrategyRegistry;
use Octarine\Repository\InMemoryFlagRepository;
use Octarine\Strategy\AlwaysOnStrategy;
use Octarine\Strategy\PercentageStrategy;
use Octarine\Strategy\WhitelistStrategy;

$repo = new InMemoryFlagRepository([
    new Flag('new_ui', true), // simple on/off
    new Flag('gradual_rollout', true, 'percentage', ['percentage' => 25, 'attribute' => 'userId']),
    new Flag('beta_users', true, 'whitelist', ['attribute' => 'email', 'values' => ['a@example.com']]),
]);

$strategies = new StrategyRegistry([
    new AlwaysOnStrategy(),
    new PercentageStrategy(),
    new WhitelistStrategy(),
]);

$flags = new FlagEvaluator($repo, $strategies);

$ctx = new Context(['userId' => '123', 'email' => 'a@example.com']);

if ($flags->isEnabled('new_ui', $ctx)) {
    // show the new UI
}

Redis (Optional)

You can configure a Redis-backed repository for centralized flags.

Storage shape expected by the built-in Redis repository:

• Hash at {prefix}:flag:{key} with fields:
  • enabled: "0" or "1"
  • strategyKey: string or empty
  • parameters: JSON object string (optional)
• Optional Set at {prefix}:flags (or custom keysSet) listing all flag keys for enumeration.

Config object and factory usage:

use Octarine\Config\OctarineConfig;
use Octarine\Config\RedisConfig;
use Octarine\Factory\RepositoryFactory;
use Octarine\Evaluator\FlagEvaluator;
use Octarine\Registry\StrategyRegistry;
use Octarine\Strategy\AlwaysOnStrategy;
use Octarine\Strategy\PercentageStrategy;
use Octarine\Strategy\WhitelistStrategy;

$config = new OctarineConfig(
    new RedisConfig(
        host: '127.0.0.1',
        port: 6379,
        password: null,
        db: 0,
        prefix: 'octarine',
        keysSet: 'octarine:flags' // optional
    )
);

// Optionally pass an existing Redis/Predis client as 2nd argument
$repo = RepositoryFactory::fromConfig($config);

$strategies = new StrategyRegistry([
    new AlwaysOnStrategy(),
    new PercentageStrategy(),
    new WhitelistStrategy(),
]);

$flags = new FlagEvaluator($repo, $strategies);

Install one of the suggested Redis clients:

• ext-redis (php-redis)
• predis/predis

Concepts

• Repository: supplies Flag definitions (in-memory provided; bring your own source)
• Strategy: evaluates flag rules (always on/off, percentage, whitelist included)
• Evaluator: orchestrates repository + strategy for a final boolean
• Context: immutable attribute bag used for targeting

Flags

Flag is a simple value object:

• key: unique flag key
• enabled: base toggle
• strategyKey: optional strategy id (e.g. percentage)
• parameters: strategy parameters (e.g. percentage, attribute, values)

Built-in Strategies

• always_on: always returns true
• always_off: always returns false
• percentage: rollout N% for users bucketed by an attribute (default userId)
• whitelist: enable only for values in a list (e.g., specific emails)

Testing

This repo includes a basic phpunit.xml.dist and sample tests under tests/.

Run tests after installing dev dependencies:

composer install
vendor/bin/phpunit

Extending

Implement Octarine\Contracts\StrategyInterface and register your strategy with StrategyRegistry.