FlagPole/SPECS.md

FlagPole Specifications

This document describes the current technical specifications and architecture of the FlagPole feature flagging library.

Core Concepts

Flag

An immutable data object representing a feature flag and its evaluation strategies.

• Properties:
  • name (string): Unique identifier.
  • enabled (bool|null): Explicit override. If true/false, evaluation stops here.
  • rolloutPercentage (int|null): 0-100 value for gradual rollout.
  • allowList (list): Keys that always receive true.
  • rules (list): Complex attribute-based targeting rules.
  • targetingKey (string|null): Optional override for the attribute used in rollout/allowList.

Context

A container for attributes (e.g., userId, email, userGroup) used during evaluation.

• Targeting Keys: By default, the evaluator looks for key, userId, id, or email (in that order), unless overridden by Flag->targetingKey.

Evaluator

The engine that applies flag strategies against a context.

• Precedence:
  1. allowList: If the targeting key is in the list, return true.
  2. enabled: If non-null, return its boolean value.
  3. rules: If any rule matches the context attributes, return true.
  4. rolloutPercentage: Hash-based stable bucketing (0-99).
  5. fallback: Returns the user-provided default.

FeatureManager

The main entry point for the consumer.

• Method: isEnabled(string $flagName, ?Context $context = null, bool $default = false): bool
• Logging: Supports PSR-3 logging of evaluation reasons.

Technical Details

Rollout Hashing

• Algorithm: xxh3(flagName + ":" + targetingKey).
• Normalization: hexdec(substr(hash, 0, 8)) % 100.
• Bucketing: 0-99.

Repositories

• FlagRepositoryInterface: Defines get(string $name) and all().
• InMemoryFlagRepository: Provided for testing and simple setups.
• JsonFileRepository: Loads flags from a JSON file. Now supports lazy-loading hydration for better performance.

FlagHydrator

A dedicated component responsible for transforming raw configuration arrays into validated Flag and Rule objects.

• Validation: Ensures all rules have required fields and valid operators (eq, neq, gt, gte, lt, lte, in, nin, contains).
• Reuse: Used by both InMemoryFlagRepository and JsonFileRepository to ensure consistent flag creation.

Constraints

• PHP 8.2+ required.
• No external dependencies (PSR interfaces excepted in future).