OpenFeature providers

PHP OpenFeature provider

Beta
View as Markdown

The Unleash OpenFeature PHP provider lets PHP applications evaluate Unleash feature flags through the OpenFeature API.

The provider wraps the Unleash PHP SDK and uses the same backend SDK behavior for fetching and caching feature flag data, local evaluation, and metrics.

Requirements

  • PHP 8.4 or later

Installation

Install the provider with Composer. The provider declares the OpenFeature PHP SDK and the Unleash PHP SDK as dependencies, together with default HTTP client and cache implementations, so you don’t need to add them separately.

$composer require unleash/openfeature-provider

Configuration

Create an UnleashBuilder with the same options you would use to configure the Unleash PHP SDK client, then pass it to an UnleashFlagProvider and register the provider with OpenFeature. The provider builds the Unleash client from the builder.

1<?php
2
3use OpenFeature\OpenFeatureAPI;
4use Unleash\Client\UnleashBuilder;
5use Unleash\OpenFeature\Provider\UnleashFlagProvider;
6
7$builder = UnleashBuilder::create()
8    ->withAppName('my-php-app')
9    ->withAppUrl('<YOUR_UNLEASH_URL>/api')
10    ->withInstanceId('my-php-app-1')
11    ->withHeader('Authorization', '<YOUR_API_TOKEN>');
12
13OpenFeatureAPI::getInstance()->setProvider(new UnleashFlagProvider($builder));

To log provider diagnostics, such as discarded context fields, pass a PSR-3 logger as the second constructor argument: new UnleashFlagProvider($builder, $logger).

Evaluate a flag

Build an OpenFeature client and evaluate flags through the OpenFeature API:

1<?php
2
3use OpenFeature\implementation\flags\EvaluationContext;
4
5$client = OpenFeatureAPI::getInstance()->getClient();
6
7$context = new EvaluationContext('user-123');
8
9$enabled = $client->getBooleanValue('my-feature', false, $context);

The provider supports all OpenFeature evaluation methods. Boolean evaluation uses the flag’s enabled state. All other types resolve from the payload of the flag’s variant:

  • String values accept string and csv payloads.
  • Integer and float values accept number payloads.
  • Object values accept json payloads.

If the flag doesn’t exist, the flag is disabled, or the variant payload is missing, has a different type, or can’t be parsed, the evaluation returns the default value. The detail methods, such as getBooleanDetails, additionally report the evaluation reason and the assigned variant name.

Context mapping

The provider maps the OpenFeature evaluation context to an Unleash context before each evaluation.

The following OpenFeature fields map directly to top-level Unleash context fields:

  • currentTime
  • userId
  • sessionId
  • remoteAddress
  • environment

If you set a targeting key, the provider maps it to userId. The targeting key takes precedence over a userId field set on the evaluation context. The appName comes from the builder configuration, not the evaluation context.

The provider adds all other scalar fields, such as strings, numbers, booleans, and date-time values, to the Unleash context properties. It discards nested values, such as arrays.

Example

To try the provider against your Unleash instance, clone the provider repository and run the boolean flag example with your Unleash URL and API token:

$composer install
$php examples/boolean_flag.php \
>  --url '<YOUR_UNLEASH_URL>/api' \
>  --api-key "$UNLEASH_API_KEY" \
>  --flag-key my-feature \
>  --targeting-key user-123