OpenFeature Providers

OpenFeature PHP Provider

ConfigDirector Provider for the OpenFeature PHP SDK

Introduction

The OpenFeature PHP Provider is intended to be used in combination with the OpenFeature PHP SDK. The provider wraps the ConfigDirector PHP SDK.

The provider receives its values the way the PHP SDK does: from a local store that the PHP processes of a host share, with one request per polling interval asking ConfigDirector for new ones for the whole host, or from the optional streaming process. The PHP SDK's How the SDK connects explains both. Evaluations read the values the provider already holds, so they make no network call.

The minimum PHP version supported is 8.3, on a 64-bit PHP.

The OpenFeature PHP SDK has no provider events, no tracking, no initialization step and no shutdown yet, so this provider leaves those out.

Installation

The provider can be installed with Composer. Its package page is on Packagist: https://packagist.org/packages/configdirector/openfeature-server-provider

The OpenFeature PHP SDK (open-feature/sdk) and the ConfigDirector PHP SDK are included as dependencies.

composer require configdirector/openfeature-server-provider

Like the SDK, the provider needs the curl and JSON extensions, and Composer refuses to install it on a 32-bit PHP. Run it on a PHP release with the fixes for CVE-2026-109618 and CVE-2026-109619: 8.3.36, 8.4.27, 8.5.12 or later. Composer also installs it on an earlier 8.3, 8.4 or 8.5 release, which ConfigDirector does not test. Composer never installs version 1.8.0 of myclabs/php-enum beside the provider, because that version makes PHP report a deprecation.

Configure and initialize the client

  1. Create an instance of the provider using your server SDK key. You can retrieve a server SDK key for each environment under SDK keys in the dashboard's navigation panel. Creating the provider reads its values.
  2. Set the OpenFeature provider.
  3. Get a client instance from OpenFeature.
index.php
use ConfigDirector\OpenFeature\ConfigDirectorProvider;
use OpenFeature\OpenFeatureAPI;

// IMPORTANT: Do not commit the server SDK key to your source code, it is a secret value.
// Creating the provider reads the values kept on this host. Only when there are none yet,
// as on the first request of a new host or container, does it ask ConfigDirector and wait
// up to the connection timeout.
$api = OpenFeatureAPI::getInstance();
$api->setProvider(new ConfigDirectorProvider(serverSdkKey: 'YOUR-SERVER-SDK-KEY'));

$client = $api->getClient('my-app', '1.0.0');
Server SDK keys are secret values. Do not commit them to your source code repository. Provide them at runtime via environment variables instead.

Create and set the provider once per request, for example in your framework's container, as the OpenFeature Slim sample does.

When no values arrive in time

Creating the provider reads the values kept in the host's local store, as the PHP SDK's initialize() does. When the local store holds none yet, as on the first request of a new host or container, it asks ConfigDirector and waits up to the connection timeout, which is 3 seconds unless you set the connection's timeout.

When no values arrive in time, or ConfigDirector rejects the server SDK key, the constructor does not throw: flags resolve to their in-code default values with the PROVIDER_NOT_READY error code, and the SDK logs why. The OpenFeature PHP SDK has no initialization step that a provider could fail, so unlike the other ConfigDirector server providers, this one does not report an error status, and your application keeps serving on in-code default values.

Additional configuration options

The provider takes the named arguments of the PHP SDK's ConfigDirector::createClient, so every option of the SDK is available on the provider.

For example, the metadata can be provided like this:

index.php
use ConfigDirector\Metadata;
use ConfigDirector\OpenFeature\ConfigDirectorProvider;

$api->setProvider(new ConfigDirectorProvider(
    serverSdkKey: 'YOUR-SERVER-SDK-KEY',
    metadata: new Metadata(appName: 'YOUR-APP-NAME', appVersion: '1.0.2'),
));

The provider accepts the same serverSdkKey, metadata, connection, logger, logLevel, telemetry and hooks arguments as the PHP SDK client, refer to the additional configuration options section of the PHP SDK for a full list. Its constructor throws ConfigDirectorValidationException for the settings createClient rejects, such as a missing key. OpenFeature's setLogger() changes nothing here: give your logger as logger.

That includes running without a connection: created with the connection mode set to ConnectionMode::Offline and no server SDK key, the provider serves the values you give it without connecting to ConfigDirector, and its constructor throws ConfigDirectorInitializationException when the values of file cannot be loaded.

The provider works with the streaming process as the SDK does: the streaming process keeps the host's local store up to date, and the provider reads from it.

Shut down

The OpenFeature PHP SDK has no shutdown. The provider's client is disposed of when the script ends, or as soon as nothing refers to the provider any longer, and then does what the PHP SDK does at the end of a request: it adds its telemetry to the local store and, when they are due, asks ConfigDirector for new values and sends the host's telemetry report.

Retrieve config values

To retrieve config values, use the OpenFeature client:

Every getter takes the flag key, the in-code default value and, optionally, the evaluation context:

index.php
$booleanValue = $client->getBooleanValue('my-config-key', false);

$stringValue = $client->getStringValue('my-string-config-key', 'Default');

Each OpenFeature getter maps to a ConfigDirector config type:

OpenFeature getterConfigDirector config value
getBooleanValueBoolean
getStringValueString, enum or URL
getIntegerValue, getFloatValueNumber
getObjectValueJSON object or JSON array

getObjectValue takes an array as its in-code default value and returns the JSON document as PHP decodes it into an array: a JSON object is an associative array, and a JSON array a list:

index.php
$settings = $client->getObjectValue('my-json-config-key', []);
$theme = $settings['theme'] ?? 'light';

For additional information regarding the OpenFeature client refer to the OpenFeature PHP SDK documentation.

Evaluation details

The detailed getters of the OpenFeature client, such as getBooleanDetails, report why an evaluation produced the value that it did:

OutcomeReasonError codeVariant
A value was foundTARGETING_MATCHThe variation name, or the value ID
A percentage rollout was skipped for a context without a targeting keyDEFAULTThe variation name, or the value ID
The config carries no valueDEFAULT
The config key is unknownERRORFLAG_NOT_FOUND
No values have arrived yetERRORPROVIDER_NOT_READY
The value does not match the requested typeERRORTYPE_MISMATCH

The Variant is the name of the variation served, such as treatment, when the config has variations and that variation has a name. Otherwise it is ConfigDirector's ID for the value served, a stable hash you can send to analytics in place of the value itself; values served in offline mode have none. In the last four cases, the in-code default value is returned.

For the three outcomes with an error code, the OpenFeature PHP SDK runs the after stage of your hooks and not their error stage, as it does for any provider that reports an error in the evaluation details.

index.php
$details = $client->getBooleanDetails('new-checkout', false, $user);
if ($details->getError() !== null) {
    error_log('new-checkout fell back to its in-code default value: ' . $details->getError()->getResolutionErrorCode()->getValue());
}

To report an experiment to an analytics tool, follow the page for Amplitude, Mixpanel, Google Analytics 4, Segment or PostHog, which names the event that tool reads.

Context

The context is the third argument of every getter of the OpenFeature client. The OpenFeature PHP provider evaluates targeting rules locally without additional network calls for different contexts.

index.php
use OpenFeature\implementation\flags\Attributes;
use OpenFeature\implementation\flags\EvaluationContext;

$user = new EvaluationContext(
    '12345', // In OpenFeature, the targeting key represents the context's identifier
    new Attributes([
        'name' => 'Example User',
        // Any arbitrary traits which can be referenced in targeting rules
        'traits' => ['region' => 'North America'],
    ]),
);

$booleanValue = $client->getBooleanValue('my-config-key', false, $user);

To evaluate flags for an entity other than a user, such as a tenant, set the context kind with a top-level kind attribute:

index.php
$tenant = new EvaluationContext(
    'acme',
    new Attributes([
        'kind' => 'tenant',
        'name' => 'Acme Inc.',
        'traits' => ['plan' => 'enterprise'],
    ]),
);

$booleanValue = $client->getBooleanValue('my-config-key', false, $tenant);

Leaving kind out means user. A kind inside traits is an ordinary trait, not the context kind. A context kind is 1 to 64 lowercase letters, digits, dashes, or underscores. A context with an invalid context kind is ignored: the SDK logs an error, and flags still resolve successfully, as if no context had been given.

The evaluation context maps onto the ConfigDirector context as follows:

OpenFeature evaluation contextConfigDirector context
The targeting key, or otherwise an id attributeid
The top-level kind attributekind
The name attributename
The traits attribute, an arraytraits
The anonymous attribute, a boolanonymous

Other attributes are not used, so put the traits your targeting rules read inside traits. An id or a name that is a number, a boolean or a date is read as text. A date is written as ISO 8601 text, inside traits too, so that date conditions can compare it. A kind that is not a string makes the provider ignore the context, as an invalid context kind does, without logging an error.

An evaluation context with neither a targeting key nor an id attribute skips percentage rollouts: a rollout does not apply to it, and the targeting rules after the rollout are tried, as they are after a conditional rule the context does not match. When none of them applies, the flag resolves to the default targeting rule value with the reason DEFAULT; a later rule that applies resolves with TARGETING_MATCH. A rule that serves a single value still applies to it. To keep an anonymous visitor in a rollout, give the context a stable targeting key, such as a session ID.

For additional information regarding the OpenFeature client refer to the OpenFeature PHP SDK documentation.

What the provider leaves out

The OpenFeature PHP SDK has no provider events, no tracking, no step that initializes a provider and no shutdown yet. So, unlike the other ConfigDirector OpenFeature providers, this one:

  • Emits no events, such as PROVIDER_READY or PROVIDER_CONFIGURATION_CHANGED. In a long-running process, the configsUpdated handler of the hooks argument tells you when values change.
  • Has no track. To report an event, such as a completed checkout, create a client with the PHP SDK's ConfigDirector::createClient(...) and the same server SDK key, and call its track.
  • Does not fail when no values arrive in time. Flags resolve with PROVIDER_NOT_READY instead, as described in When no values arrive in time.
  • Is not shut down. Its client disposes of itself, as described in Shut down.

Test your code

Code that reads flags through OpenFeature is tested by swapping the provider, so it never has to change for a test. The OpenFeature PHP SDK ships no in-memory provider, so in a test, set a ConfigDirector provider in offline mode with the values the test needs. It needs no server SDK key, never connects to ConfigDirector and sends nothing:

tests/CheckoutTest.php
use ConfigDirector\ConnectionMode;
use ConfigDirector\ConnectionOptions;
use ConfigDirector\OpenFeature\ConfigDirectorProvider;
use OpenFeature\OpenFeatureAPI;
use PHPUnit\Framework\TestCase;

final class CheckoutTest extends TestCase
{
    public function testShowsTheNewCheckout(): void
    {
        $api = OpenFeatureAPI::getInstance();
        $api->setProvider(new ConfigDirectorProvider(
            connection: new ConnectionOptions(mode: ConnectionMode::Offline, values: ['new-checkout' => true, 'max-items' => 20]),
        ));
        $client = $api->getClient('checkout-tests', '1.0.0');

        self::assertTrue($client->getBooleanValue('new-checkout', false));
        self::assertSame(20, $client->getIntegerValue('max-items', 0));
    }
}

Every evaluation context receives the same value from an offline provider. To change a value during a test, set a new provider with the new values. The OpenFeature API is one instance for the whole process, so each test sets the provider it needs before it reads. The examples use PHPUnit; any test framework works just as well.