OpenFeature PHP Provider
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
- Create an instance of the provider using your server SDK key. You can retrieve a server SDK key for each environment under
SDK keysin the dashboard's navigation panel. Creating the provider reads its values. - Set the OpenFeature provider.
- Get a client instance from OpenFeature.
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');
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:
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:
$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 getter | ConfigDirector config value |
|---|---|
getBooleanValue | Boolean |
getStringValue | String, enum or URL |
getIntegerValue, getFloatValue | Number |
getObjectValue | JSON 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:
$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:
| Outcome | Reason | Error code | Variant |
|---|---|---|---|
| A value was found | TARGETING_MATCH | The variation name, or the value ID | |
| A percentage rollout was skipped for a context without a targeting key | DEFAULT | The variation name, or the value ID | |
| The config carries no value | DEFAULT | ||
| The config key is unknown | ERROR | FLAG_NOT_FOUND | |
| No values have arrived yet | ERROR | PROVIDER_NOT_READY | |
| The value does not match the requested type | ERROR | TYPE_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.
$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.
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:
$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 context | ConfigDirector context |
|---|---|
The targeting key, or otherwise an id attribute | id |
The top-level kind attribute | kind |
The name attribute | name |
The traits attribute, an array | traits |
The anonymous attribute, a bool | anonymous |
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_READYorPROVIDER_CONFIGURATION_CHANGED. In a long-running process, theconfigsUpdatedhandler of thehooksargument tells you when values change. - Has no
track. To report an event, such as a completed checkout, create a client with the PHP SDK'sConfigDirector::createClient(...)and the same server SDK key, and call itstrack. - Does not fail when no values arrive in time. Flags resolve with
PROVIDER_NOT_READYinstead, 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:
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.