83 lines
3 KiB
Markdown
83 lines
3 KiB
Markdown
# FlagPole
|
|
|
|
Feature flag handling for PHP. Simple, framework-agnostic, and lightweight.
|
|
|
|
|
|
|
|
[](https://packagist.org/packages/getphred/pairity)
|
|
[](LICENSE.md)
|
|
|
|
## Installation
|
|
|
|
Install via Composer:
|
|
|
|
```
|
|
composer require phred/flagpole
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```php
|
|
use FlagPole\FeatureManager;
|
|
use FlagPole\Context;
|
|
use FlagPole\Repository\InMemoryFlagRepository;
|
|
|
|
require __DIR__ . '/vendor/autoload.php';
|
|
|
|
$repo = InMemoryFlagRepository::fromArray([
|
|
'new-dashboard' => [
|
|
'enabled' => null, // not a hard on/off
|
|
'rolloutPercentage' => 25, // 25% gradual rollout
|
|
'allowList' => ['user_1'], // always on for specific users
|
|
'rules' => [ // attribute-based rules
|
|
['attribute' => 'plan', 'operator' => 'eq', 'value' => 'pro'],
|
|
],
|
|
],
|
|
'hard-off' => [ 'enabled' => false ],
|
|
'hard-on' => [ 'enabled' => true ],
|
|
]);
|
|
|
|
$flags = new FeatureManager($repo);
|
|
|
|
$context = Context::fromArray(['userId' => 'user_42', 'plan' => 'pro']);
|
|
|
|
if ($flags->isEnabled('new-dashboard', $context, false)) {
|
|
// show the new dashboard
|
|
} else {
|
|
// keep the old dashboard
|
|
}
|
|
```
|
|
|
|
## Concepts
|
|
|
|
- Flag: has a `name` and optional strategies:
|
|
- `enabled`: explicit boolean on/off overrides everything.
|
|
- `allowList`: list of user keys that always get the flag enabled.
|
|
- `rules`: complex attribute targeting (e.g. `version > 2.0`, `plan == 'pro'`).
|
|
- `rolloutPercentage`: 0-100 gradual rollout based on a stable hash.
|
|
- Context: attributes about the subject (e.g. `userId`, `email`) used for evaluation.
|
|
- Repository: source of truth for flags. Provided: `InMemoryFlagRepository`, `JsonFileRepository`.
|
|
- Hydration: `FlagHydrator` centralizes flag creation and provides validation for targeting rules.
|
|
- Observability: Optional PSR-3 logging of evaluation results and reasons.
|
|
|
|
## Targeting key
|
|
|
|
Evaluator looks for a stable key in the context in this order: `key`, `userId`, `id`, `email`.
|
|
You can also specify an explicit `targetingKey` per flag to use a specific attribute (e.g. `orgId`).
|
|
|
|
## Precedence semantics
|
|
|
|
When evaluating a flag, the following precedence applies:
|
|
1. `allowList` — if the targeting key is in the allow-list, the flag is enabled.
|
|
2. `enabled` — explicit on/off overrides everything below.
|
|
3. `rules` — attribute-based targeting rules.
|
|
4. `rolloutPercentage` — uses stable bucketing over the targeting key.
|
|
5. Fallback — returns the provided default when none of the above apply.
|
|
|
|
## Framework integration
|
|
|
|
FlagPole is framework-agnostic. Wrap `FeatureManager` in your framework's container and bind a repository suitable for your environment.
|
|
|
|
## License
|
|
|
|
MIT |