FlagPole/MILESTONES.md

FlagPole Milestones

This document outlines the roadmap for enhancing FlagPole with advanced targeting, persistence, and observability features.

Table of Contents

• Milestone 1: Advanced Rule Engine
• Milestone 2: Pluggable Targeting Keys
• Milestone 3: Persistent Repositories
• Milestone 4: Observability & Logging
• Milestone 5: Documentation & Polish
• Milestone 6: Refactoring & DRY
• Milestone 7: Validation & Safety

Milestone 1: Advanced Rule Engine

Move beyond simple allow-lists to support complex attribute-based targeting.

• Define Rule DTO/Interface (src/Rule.php).
• Add rules collection to Flag DTO.
• Implement rule evaluation logic in Evaluator (supporting operators like eq, gt, lt, in, contains).
• Update Evaluator::evaluate precedence: allowList > enabled > rules > rolloutPercentage.

Milestone 2: Pluggable Targeting Keys

Allow explicit control over which context attribute is used for rollout hashing.

• Add optional targetingKey property to Flag.
• Refactor Evaluator::resolveTargetingKey to honor Flag->targetingKey if present.
• Modernize hashing implementation in Evaluator::computeBucket for PHP 8.2+.

Milestone 3: Persistent Repositories

Provide out-of-the-box support for non-volatile flag storage.

• Implement JsonFileRepository in src/Repository/JsonFileRepository.php.
• Ensure robust JSON parsing and mapping to Flag objects.

Milestone 4: Observability & Logging

Provide insights into why flags are being enabled or disabled.

• Integrate PSR-3 LoggerInterface into FeatureManager and Evaluator.
• Implement detailed logging for evaluation outcomes (e.g., which rule or strategy matched).
• (Optional) Create EvaluationResult DTO for programmatic access to evaluation reasons.

Milestone 5: Documentation & Polish

• Update README.md with examples for new features.
• Add comprehensive tests for Rule Engine and JSON Repository.
• Verify zero regression for existing simple flag usage.

Milestone 6: Refactoring & DRY

Centralize logic and remove duplication to improve maintainability.

• Extract flag hydration logic into a dedicated FlagHydrator class to be reused across repositories.
• Refactor InMemoryFlagRepository to use the new hydration logic.
• Refactor JsonFileRepository to use the new hydration logic.

Milestone 7: Validation & Safety

Enhance the engine to be more robust and developer-friendly.

• Add validation to the rule engine to handle or log unknown operators instead of failing silently.
• Implement configuration validation to ensure Flag and Rule objects are correctly formed before evaluation.
• Optimize JsonFileRepository to avoid unnecessary parsing or consider lazy-loading if the config grows large.