diff --git a/docs/reference/sdks/client/kotlin.mdx b/docs/reference/sdks/client/kotlin.mdx index cdd3bd09c..d98caa74e 100644 --- a/docs/reference/sdks/client/kotlin.mdx +++ b/docs/reference/sdks/client/kotlin.mdx @@ -10,7 +10,7 @@ This content has been automatically generated from kotlin-sdk. Edits should be made here: https://github.com/open-feature/kotlin-sdk Once a repo has been updated, docs can be generated by running: yarn update:sdk-docs -Last updated at Mon Jun 08 2026 09:46:34 GMT+0000 (Coordinated Universal Time) +Last updated at Wed Jul 01 2026 09:19:01 GMT+0000 (Coordinated Universal Time) --> import MCPInstall from '@site/src/partials/mcp-install'; diff --git a/docs/reference/sdks/client/swift.mdx b/docs/reference/sdks/client/swift.mdx index a975bf295..fcaaa96af 100644 --- a/docs/reference/sdks/client/swift.mdx +++ b/docs/reference/sdks/client/swift.mdx @@ -10,7 +10,7 @@ This content has been automatically generated from swift-sdk. Edits should be made here: https://github.com/open-feature/swift-sdk Once a repo has been updated, docs can be generated by running: yarn update:sdk-docs -Last updated at Mon Jun 08 2026 09:46:35 GMT+0000 (Coordinated Universal Time) +Last updated at Wed Jul 01 2026 09:19:01 GMT+0000 (Coordinated Universal Time) --> import MCPInstall from '@site/src/partials/mcp-install'; diff --git a/docs/reference/sdks/client/web/angular.mdx b/docs/reference/sdks/client/web/angular.mdx index 9b0183c31..26abbca4e 100644 --- a/docs/reference/sdks/client/web/angular.mdx +++ b/docs/reference/sdks/client/web/angular.mdx @@ -10,7 +10,7 @@ This content has been automatically generated from js-sdk. Edits should be made here: https://github.com/open-feature/js-sdk Once a repo has been updated, docs can be generated by running: yarn update:sdk-docs -Last updated at Mon Jun 08 2026 09:46:35 GMT+0000 (Coordinated Universal Time) +Last updated at Wed Jul 01 2026 09:19:01 GMT+0000 (Coordinated Universal Time) -->

@@ -18,8 +18,8 @@ Last updated at Mon Jun 08 2026 09:46:35 GMT+0000 (Coordinated Universal Time) Specification - - Release + + Release
@@ -46,8 +46,8 @@ In addition to the features provided by the [web sdk](/docs/reference/sdks/clien - [yarn](#yarn) - [Required peer dependencies](#required-peer-dependencies) - [Usage](#usage) - - [Module](#module) - - [Minimal Example](#minimal-example) + - [Standalone configuration (recommended)](#standalone-configuration-recommended) + - [NgModule configuration (deprecated)](#ngmodule-configuration-deprecated) - [How to use](#how-to-use) - [Structural Directives](#structural-directives) - [Boolean Feature Flag](#boolean-feature-flag) @@ -100,9 +100,44 @@ See the [package.json](https://github.com/open-feature/js-sdk/blob/main/packages ### Usage -#### Module +#### Standalone configuration (recommended) -To configure OpenFeature for your application, import the `OpenFeatureModule` and call `forRoot` to register the provider(s) and optional evaluation context. +For standalone / `bootstrapApplication`-based apps, pass `provideOpenFeature()` in the `providers` array of your `ApplicationConfig`: + +```typescript +import { ApplicationConfig } from '@angular/core'; +import { provideOpenFeature } from '@openfeature/angular-sdk'; + +export const appConfig: ApplicationConfig = { + providers: [ + provideOpenFeature({ + provider: yourFeatureProvider, + // domainBoundProviders are optional, mostly needed if more than one provider is used in the application. + domainBoundProviders: { + domain1: new YourOpenFeatureProvider(), + domain2: new YourOtherOpenFeatureProvider(), + }, + }), + ], +}; +``` + +Then bootstrap your app with this config: + +```typescript +import { bootstrapApplication } from '@angular/platform-browser'; +import { AppComponent } from './app/app.component'; +import { appConfig } from './app/app.config'; + +bootstrapApplication(AppComponent, appConfig); +``` + +#### NgModule configuration (deprecated) + +> [!WARNING] +> `OpenFeatureModule` and `forRoot()` are deprecated. Use [`provideOpenFeature()`](#standalone-configuration-recommended) instead. + +To configure OpenFeature for NgModule-based applications, import the `OpenFeatureModule` and call `forRoot` to register the provider(s) and optional evaluation context. ```typescript import { NgModule } from '@angular/core'; @@ -358,20 +393,19 @@ const flag$ = this.flagService.getBooleanDetails('my-flag', false, 'my-domain', ##### Setting evaluation context -To set the initial evaluation context, you can add the `context` parameter to the `OpenFeatureModule` configuration. +To set the initial evaluation context, you can add the `context` parameter to the `provideOpenFeature()` configuration. This context can be either an object or a factory function that returns an `EvaluationContext`. > [!TIP] > Updating the context can be done directly via the global OpenFeature API using `OpenFeature.setContext()` -Here’s how you can define and use the initial client evaluation context: +Here's how you can define and use the initial client evaluation context: ###### Using a static object ```typescript -import { NgModule } from '@angular/core'; -import { CommonModule } from '@angular/common'; -import { OpenFeatureModule } from '@openfeature/angular-sdk'; +import { ApplicationConfig } from '@angular/core'; +import { provideOpenFeature } from '@openfeature/angular-sdk'; const initialContext = { user: { @@ -380,37 +414,32 @@ const initialContext = { }, }; -@NgModule({ - imports: [ - CommonModule, - OpenFeatureModule.forRoot({ +export const appConfig: ApplicationConfig = { + providers: [ + provideOpenFeature({ provider: yourFeatureProvider, context: initialContext, }), ], -}) -export class AppModule {} +}; ``` ###### Using a factory function ```typescript -import { NgModule } from '@angular/core'; -import { CommonModule } from '@angular/common'; -import { OpenFeatureModule, EvaluationContext } from '@openfeature/angular-sdk'; +import { ApplicationConfig } from '@angular/core'; +import { provideOpenFeature, EvaluationContext } from '@openfeature/angular-sdk'; const contextFactory = (): EvaluationContext => loadContextFromLocalStorage(); -@NgModule({ - imports: [ - CommonModule, - OpenFeatureModule.forRoot({ +export const appConfig: ApplicationConfig = { + providers: [ + provideOpenFeature({ provider: yourFeatureProvider, context: contextFactory, }), ], -}) -export class AppModule {} +}; ``` ##### Observability considerations diff --git a/docs/reference/sdks/client/web/index.mdx b/docs/reference/sdks/client/web/index.mdx index be199c58d..267dd1d79 100644 --- a/docs/reference/sdks/client/web/index.mdx +++ b/docs/reference/sdks/client/web/index.mdx @@ -10,7 +10,7 @@ This content has been automatically generated from js-sdk. Edits should be made here: https://github.com/open-feature/js-sdk Once a repo has been updated, docs can be generated by running: yarn update:sdk-docs -Last updated at Mon Jun 08 2026 09:46:34 GMT+0000 (Coordinated Universal Time) +Last updated at Wed Jul 01 2026 09:19:00 GMT+0000 (Coordinated Universal Time) --> import MCPInstall from '@site/src/partials/mcp-install'; @@ -20,8 +20,8 @@ import MCPInstall from '@site/src/partials/mcp-install'; Specification - - Release + + Release
diff --git a/docs/reference/sdks/client/web/react.mdx b/docs/reference/sdks/client/web/react.mdx index 32c16bd41..3aaffa094 100644 --- a/docs/reference/sdks/client/web/react.mdx +++ b/docs/reference/sdks/client/web/react.mdx @@ -10,7 +10,7 @@ This content has been automatically generated from js-sdk. Edits should be made here: https://github.com/open-feature/js-sdk Once a repo has been updated, docs can be generated by running: yarn update:sdk-docs -Last updated at Mon Jun 08 2026 09:46:34 GMT+0000 (Coordinated Universal Time) +Last updated at Wed Jul 01 2026 09:19:01 GMT+0000 (Coordinated Universal Time) --> import MCPInstall from '@site/src/partials/mcp-install'; @@ -20,8 +20,8 @@ import MCPInstall from '@site/src/partials/mcp-install'; Specification - - Release + + Release
diff --git a/docs/reference/sdks/server/cpp.mdx b/docs/reference/sdks/server/cpp.mdx index c15152f02..44ff8c815 100644 --- a/docs/reference/sdks/server/cpp.mdx +++ b/docs/reference/sdks/server/cpp.mdx @@ -9,7 +9,7 @@ This content has been automatically generated from cpp-sdk. Edits should be made here: https://github.com/open-feature/cpp-sdk Once a repo has been updated, docs can be generated by running: yarn update:sdk-docs -Last updated at Mon Jun 08 2026 09:46:36 GMT+0000 (Coordinated Universal Time) +Last updated at Wed Jul 01 2026 09:19:02 GMT+0000 (Coordinated Universal Time) -->

diff --git a/docs/reference/sdks/server/dart.mdx b/docs/reference/sdks/server/dart.mdx index 22e51ac72..c203a0d4d 100644 --- a/docs/reference/sdks/server/dart.mdx +++ b/docs/reference/sdks/server/dart.mdx @@ -9,7 +9,7 @@ This content has been automatically generated from dart-server-sdk. Edits should be made here: https://github.com/open-feature/dart-server-sdk Once a repo has been updated, docs can be generated by running: yarn update:sdk-docs -Last updated at Mon Jun 08 2026 09:46:35 GMT+0000 (Coordinated Universal Time) +Last updated at Wed Jul 01 2026 09:19:01 GMT+0000 (Coordinated Universal Time) -->

diff --git a/docs/reference/sdks/server/dotnet.mdx b/docs/reference/sdks/server/dotnet.mdx index acb6e8a18..024765b19 100644 --- a/docs/reference/sdks/server/dotnet.mdx +++ b/docs/reference/sdks/server/dotnet.mdx @@ -10,15 +10,15 @@ This content has been automatically generated from dotnet-sdk. Edits should be made here: https://github.com/open-feature/dotnet-sdk Once a repo has been updated, docs can be generated by running: yarn update:sdk-docs -Last updated at Mon Jun 08 2026 09:46:33 GMT+0000 (Coordinated Universal Time) +Last updated at Wed Jul 01 2026 09:19:00 GMT+0000 (Coordinated Universal Time) --> import MCPInstall from '@site/src/partials/mcp-install'; [![Specification](https://img.shields.io/static/v1?label=specification&message=v0.8.0&color=yellow&style=for-the-badge)](https://github.com/open-feature/spec/releases/tag/v0.8.0) [ -![Release](https://img.shields.io/static/v1?label=release&message=v2.13.0&color=blue&style=for-the-badge) -](https://github.com/open-feature/dotnet-sdk/releases/tag/v2.13.0) +![Release](https://img.shields.io/static/v1?label=release&message=v2.14.0&color=blue&style=for-the-badge) +](https://github.com/open-feature/dotnet-sdk/releases/tag/v2.14.0) [![Slack](https://img.shields.io/badge/slack-%40cncf%2Fopenfeature-brightgreen?style=flat&logo=slack)](https://cloud-native.slack.com/archives/C0344AANLA1) [![Codecov](https://codecov.io/gh/open-feature/dotnet-sdk/branch/main/graph/badge.svg?token=MONAVJBXUJ)](https://codecov.io/gh/open-feature/dotnet-sdk) @@ -643,6 +643,9 @@ services.AddOpenFeature(builder => ### Trace Enricher Hook +> [!WARNING] +> As of v2.14, the OpenFeature SDK emits native OpenTelemetry spans for every flag evaluation without requiring any hooks. Use `TraceEnricherHook` when you want activities/spans **outside** of OpenFeature to be enriched with flag evaluation data. If you are already using `TraceEnricherHook`, you may see **new spans** appear in your observability platform after upgrading to v2.14. + The `TraceEnricherHook` enriches telemetry traces with additional information during the feature flag evaluation lifecycle. This hook adds relevant flag evaluation details as tags and events to the current `Activity` for tracing purposes. For this hook to function correctly, an active span must be set in the current `Activity`, otherwise the hook will no-op. @@ -662,6 +665,9 @@ Below are the tags added to the trace event: | error.type | Describes a class of error the operation ended with | Evaluation details (if error) | | error.message | A message explaining the nature of an error occurring during flag evaluation | Evaluation details (if error) | +> [!NOTE] +> To receive OpenTelemetry traces emitted natively by the OpenFeature SDK, add `.AddSource("OpenFeature")` to your `TracerProviderBuilder`. No hooks are required. + #### Example The following example demonstrates the use of the `TraceEnricherHook` with the `OpenFeature dotnet-sdk`. The traces are sent to a `jaeger` OTLP collector running at `localhost:4317`. @@ -682,6 +688,7 @@ namespace OpenFeatureTestApp // set up the OpenTelemetry OTLP exporter var tracerProvider = Sdk.CreateTracerProviderBuilder() + .AddSource("OpenFeature") // receive traces from OpenFeature SDK .AddSource("my-tracer") .ConfigureResource(r => r.AddService("jaeger-test")) .AddOtlpExporter(o => diff --git a/docs/reference/sdks/server/go.mdx b/docs/reference/sdks/server/go.mdx index 1a316a6e8..42e56b575 100644 --- a/docs/reference/sdks/server/go.mdx +++ b/docs/reference/sdks/server/go.mdx @@ -9,7 +9,7 @@ This content has been automatically generated from go-sdk. Edits should be made here: https://github.com/open-feature/go-sdk Once a repo has been updated, docs can be generated by running: yarn update:sdk-docs -Last updated at Mon Jun 08 2026 09:46:33 GMT+0000 (Coordinated Universal Time) +Last updated at Wed Jul 01 2026 09:19:00 GMT+0000 (Coordinated Universal Time) --> import MCPInstall from '@site/src/partials/mcp-install'; @@ -71,7 +71,7 @@ func main() { // Register your feature flag provider openfeature.SetProviderAndWait(openfeature.NoopProvider{}) // Create a new client - client := openfeature.NewClient("app") + client := openfeature.NewDefaultClient() // Evaluate your feature flag v2Enabled := client.Boolean( context.TODO(), "v2_enabled", true, openfeature.EvaluationContext{}, @@ -137,7 +137,7 @@ openfeature.SetEvaluationContext(openfeature.NewTargetlessEvaluationContext( )) // set a value to the client context -client := openfeature.NewClient("my-app") +client := openfeature.NewDefaultClient() client.SetEvaluationContext(openfeature.NewTargetlessEvaluationContext( map[string]any{ "version": "1.4.6", @@ -151,7 +151,7 @@ evalCtx := openfeature.NewEvaluationContext( "company": "Initech", }, ) -boolValue, err := client.BooleanValue(context.TODO(), "boolFlag", false, evalCtx) +boolValue := client.Boolean(context.TODO(), "boolFlag", false, evalCtx) ``` ### Hooks @@ -167,11 +167,11 @@ Once you've added a hook as a dependency, it can be registered at the global, cl openfeature.AddHooks(ExampleGlobalHook{}) // add a hook on this client, to run on all evaluations made by this client -client := openfeature.NewClient("my-app") +client := openfeature.NewDefaultClient() client.AddHooks(ExampleClientHook{}) // add a hook for this evaluation only -value, err := client.BooleanValue( +value := client.Boolean( context.TODO(), "boolFlag", false, openfeature.EvaluationContext{}, openfeature.WithHooks(ExampleInvocationHook{}), ) ``` @@ -184,7 +184,7 @@ For example, a flag enhancing the appearance of a UI component might drive user ```go // initialize a client -client := openfeature.NewClient("my-app") +client := openfeature.NewDefaultClient() // trigger tracking event action client.Track( @@ -332,7 +332,7 @@ ec := openfeature.TransactionContext(ctx) tCtx := openfeature.MergeTransactionContext(ctx, openfeature.EvaluationContext{}) // use TransactionContext in a flag evaluation -client.BooleanValue(tCtx, ....) +_ = client.Boolean(tCtx, ....) ``` ### Multi-Provider Implementation diff --git a/docs/reference/sdks/server/java.mdx b/docs/reference/sdks/server/java.mdx index 123c2205e..211c47b52 100644 --- a/docs/reference/sdks/server/java.mdx +++ b/docs/reference/sdks/server/java.mdx @@ -9,7 +9,7 @@ This content has been automatically generated from java-sdk. Edits should be made here: https://github.com/open-feature/java-sdk Once a repo has been updated, docs can be generated by running: yarn update:sdk-docs -Last updated at Mon Jun 08 2026 09:46:33 GMT+0000 (Coordinated Universal Time) +Last updated at Wed Jul 01 2026 09:18:59 GMT+0000 (Coordinated Universal Time) --> import MCPInstall from '@site/src/partials/mcp-install'; @@ -20,8 +20,8 @@ import MCPInstall from '@site/src/partials/mcp-install'; - - Release + + Release @@ -59,7 +59,7 @@ Note that this library is intended to be used in server-side contexts and has no dev.openfeature sdk - 1.20.2 + 1.21.0 ``` @@ -82,7 +82,7 @@ If you would like snapshot builds, this is the relevant repository information: ```groovy dependencies { - implementation 'dev.openfeature:sdk:1.20.2' + implementation 'dev.openfeature:sdk:1.21.0' } ``` @@ -213,15 +213,15 @@ If the flag management system you're using supports targeting, you can provide t // set a value to the global context OpenFeatureAPI api = OpenFeatureAPI.getInstance(); Map apiAttrs = new HashMap<>(); -apiAttrs.put("region", new Value(System.getEnv("us-east-1"))); +apiAttrs.put("region", new Value(System.getenv("AWS_REGION"))); EvaluationContext apiCtx = new ImmutableContext(apiAttrs); api.setEvaluationContext(apiCtx); // set a value to the client context Map clientAttrs = new HashMap<>(); -clientAttrs.put("region", new Value(System.getEnv("us-east-1"))); +clientAttrs.put("region", new Value(System.getenv("AWS_REGION"))); EvaluationContext clientCtx = new ImmutableContext(clientAttrs); -Client client = api.getInstance().getClient(); +Client client = api.getClient(); client.setEvaluationContext(clientCtx); // set a value to the invocation context @@ -288,7 +288,7 @@ If a domain has no associated provider, the global provider is used. FeatureProvider scopedProvider = new MyProvider(); // registering the default provider -OpenFeatureAPI.getInstance().setProvider(LocalProvider()); +OpenFeatureAPI.getInstance().setProvider(new LocalProvider()); // registering a provider to a domain OpenFeatureAPI.getInstance().setProvider("my-domain", new CachedProvider()); @@ -448,25 +448,26 @@ This can be a new repository or included in [the existing contrib repository](ht Implement your own hook by conforming to the `Hook interface`. ```java -class MyHook implements Hook { +class MyHook implements Hook { @Override - public Optional before(HookContext ctx, Map hints) { + public Optional before(HookContext ctx, Map hints) { // code that runs before the flag evaluation + return Optional.empty(); } @Override - public void after(HookContext ctx, FlagEvaluationDetails details, Map hints) { + public void after(HookContext ctx, FlagEvaluationDetails details, Map hints) { // code that runs after the flag evaluation succeeds } @Override - public void error(HookContext ctx, Exception error, Map hints) { + public void error(HookContext ctx, Exception error, Map hints) { // code that runs when there's an error during a flag evaluation } @Override - public void finallyAfter(HookContext ctx, FlagEvaluationDetails details, Map hints) { + public void finallyAfter(HookContext ctx, FlagEvaluationDetails details, Map hints) { // code that runs regardless of success or error } }; diff --git a/docs/reference/sdks/server/javascript/index.mdx b/docs/reference/sdks/server/javascript/index.mdx index bd6f4d5d7..ad64c80f6 100644 --- a/docs/reference/sdks/server/javascript/index.mdx +++ b/docs/reference/sdks/server/javascript/index.mdx @@ -10,7 +10,7 @@ This content has been automatically generated from js-sdk. Edits should be made here: https://github.com/open-feature/js-sdk Once a repo has been updated, docs can be generated by running: yarn update:sdk-docs -Last updated at Mon Jun 08 2026 09:46:33 GMT+0000 (Coordinated Universal Time) +Last updated at Wed Jul 01 2026 09:18:59 GMT+0000 (Coordinated Universal Time) --> import MCPInstall from '@site/src/partials/mcp-install'; @@ -20,8 +20,8 @@ import MCPInstall from '@site/src/partials/mcp-install'; Specification - - Release + + Release
diff --git a/docs/reference/sdks/server/javascript/nestjs.mdx b/docs/reference/sdks/server/javascript/nestjs.mdx index 218f08638..8ef0b1030 100644 --- a/docs/reference/sdks/server/javascript/nestjs.mdx +++ b/docs/reference/sdks/server/javascript/nestjs.mdx @@ -10,7 +10,7 @@ This content has been automatically generated from js-sdk. Edits should be made here: https://github.com/open-feature/js-sdk Once a repo has been updated, docs can be generated by running: yarn update:sdk-docs -Last updated at Mon Jun 08 2026 09:46:33 GMT+0000 (Coordinated Universal Time) +Last updated at Wed Jul 01 2026 09:18:59 GMT+0000 (Coordinated Universal Time) --> import MCPInstall from '@site/src/partials/mcp-install'; @@ -20,8 +20,8 @@ import MCPInstall from '@site/src/partials/mcp-install'; Specification - - Release + + Release
diff --git a/docs/reference/sdks/server/php.mdx b/docs/reference/sdks/server/php.mdx index 0cc027895..e7512d572 100644 --- a/docs/reference/sdks/server/php.mdx +++ b/docs/reference/sdks/server/php.mdx @@ -9,7 +9,7 @@ This content has been automatically generated from php-sdk. Edits should be made here: https://github.com/open-feature/php-sdk Once a repo has been updated, docs can be generated by running: yarn update:sdk-docs -Last updated at Mon Jun 08 2026 09:46:34 GMT+0000 (Coordinated Universal Time) +Last updated at Wed Jul 01 2026 09:19:00 GMT+0000 (Coordinated Universal Time) --> import MCPInstall from '@site/src/partials/mcp-install'; @@ -21,8 +21,8 @@ import MCPInstall from '@site/src/partials/mcp-install'; - - Release + + Release @@ -144,6 +144,7 @@ class MyClass | ✅ | [Targeting](#targeting) | Contextually-aware flag evaluation using [evaluation context](/docs/reference/concepts/evaluation-context). | | ✅ | [Hooks](#hooks) | Add functionality to various stages of the flag evaluation life-cycle. | | ✅ | [Logging](#logging) | Integrate with popular logging packages. | +| ✅ | [MultiProvider](#multiprovider) | Combine multiple providers with configurable evaluation strategies for fallback and aggregation. | | ❌ | [Named clients](#named-clients) | Utilize multiple providers in a single application. | | ⚠️ | [Eventing](#eventing) | React to state changes in the provider or flag management system. | | ❌ | [Shutdown](#shutdown) | Gracefully clean up a provider during application shutdown. | @@ -167,6 +168,358 @@ $api->setProvider(new MyProvider()); +#### MultiProvider + +The Multi-Provider allows you to use multiple underlying providers as sources of flag data for the OpenFeature SDK. When a flag is being evaluated, the Multi-Provider will consult each underlying provider it is managing in order to determine the final result. Different evaluation strategies can be defined to control which providers get evaluated and which result is used. + +The Multi-Provider is a powerful tool for performing migrations between flag providers, or combining multiple providers into a single feature flagging interface. For example: + +- **Migration**: When migrating between two providers, you can run both in parallel under a unified flagging interface. As flags are added to the new provider, the Multi-Provider will automatically find and return them, falling back to the old provider if the new provider does not have the flag. +- **Multiple Data Sources**: The Multi-Provider allows you to seamlessly combine many sources of flagging data, such as environment variables, local files, database values, and SaaS-hosted feature management systems. +- **High Availability**: Use multiple providers as redundant sources, automatically failing over when one provider is unavailable. + +**Basic Usage** + +The Multi-Provider is initialized with an array of providers it should evaluate: + +```php +use OpenFeature\OpenFeatureAPI; +use OpenFeature\implementation\multiprovider\MultiProvider; + +$multiProvider = new MultiProvider([ + ['provider' => new ProviderA()], + ['provider' => new ProviderB()], +]); + +$api = OpenFeatureAPI::getInstance(); +$api->setProvider($multiProvider); + +$client = $api->getClient(); +echo $client->getBooleanValue('my-flag', false); +``` + +By default, the Multi-Provider will evaluate all underlying providers in order and return the **first successful result**. If a provider indicates it does not have a flag (`FLAG_NOT_FOUND` error code), then it will be skipped and the next provider will be evaluated. If any provider throws or returns an error result, the operation will fail and the error will be returned. If no provider returns a successful result, the operation will fail with a `FLAG_NOT_FOUND` error code. + +To change this behaviour, a different "strategy" can be provided: + +```php +use OpenFeature\implementation\multiprovider\strategy\FirstSuccessfulStrategy; + +$multiProvider = new MultiProvider([ + ['provider' => new ProviderA()], + ['provider' => new ProviderB()], +], new FirstSuccessfulStrategy()); +``` + +The Multi-Provider comes with three strategies out of the box: + +1. **FirstMatchStrategy** (default): Evaluates all providers in order and returns the first successful result. Providers that indicate `FLAG_NOT_FOUND` error will be skipped and the next provider will be evaluated. Any other error will cause the operation to fail and the error to be returned. +2. **FirstSuccessfulStrategy**: Evaluates all providers in order and returns the first successful result. Any error will cause that provider to be skipped. If no successful result is returned, the set of errors will be returned. +3. **ComparisonStrategy**: Evaluates all providers at one time. If every provider returns a successful result with the same value, then that result is returned. Otherwise, an error is returned immediately if any provider errors. When values do not agree, an optional callback will be executed to notify you of the mismatch, and the configured "fallback provider" value will be used. This can be useful when migrating between providers that are expected to contain identical configuration. You can easily spot mismatches in configuration without affecting flag behaviour. + +**Provider Naming** + +Providers can be named explicitly or have names auto-generated: + +```php +// Explicit naming (recommended for clarity) +new MultiProvider([ + ['name' => 'LaunchDarkly', 'provider' => $ldProvider], + ['name' => 'FlagSmith', 'provider' => $fsProvider], +]); + +// Auto-generated naming (provider class name is used) +new MultiProvider([ + ['provider' => $ldProvider], // Named "launchdarkly" (lowercase) + ['provider' => $fsProvider], // Named "flagsmith" (lowercase) + ['provider' => $fsProvider], // Named "flagsmith_2" (auto-incremented, lowercase) +]); +``` + +> **Note:** Provider names are **case-insensitive** and stored in lowercase. "MyProvider", "myprovider", and "MYPROVIDER" are all treated as the same provider name. Auto-generated names from provider metadata are also normalized to lowercase. + +**Strategies** + +##### FirstMatchStrategy (Default) + +Evaluates providers sequentially and returns the **first successful result**. Continues to the next provider only if the current one throws a `FLAG_NOT_FOUND` error. + +**Use cases:** +- Primary/fallback provider setup +- Gradual migration between providers +- Provider priority ordering + +```php +use OpenFeature\implementation\multiprovider\strategy\FirstMatchStrategy; + +$multiProvider = new MultiProvider([ + ['name' => 'Remote', 'provider' => new RemoteProvider()], // Try remote first + ['name' => 'Cache', 'provider' => new CacheProvider()], // Fall back to cache + ['name' => 'Default', 'provider' => new DefaultProvider()], // Final fallback +], new FirstMatchStrategy()); +``` + +**Behavior:** +- **Remote** has the flag → returns Remote's value ✅ +- **Remote** throws `FLAG_NOT_FOUND` → continues to **Cache** +- **Remote** throws other error (e.g., network timeout) → stops and returns error ❌ +- All providers throw `FLAG_NOT_FOUND` → returns default value with aggregated errors + +##### FirstSuccessfulStrategy + +Evaluates providers sequentially and returns the **first successful result**, skipping providers that throw **any error** (not just `FLAG_NOT_FOUND`). + +**Use cases:** +- High availability setups +- Tolerating provider failures +- Failover scenarios + +```php +use OpenFeature\implementation\multiprovider\strategy\FirstSuccessfulStrategy; + +$multiProvider = new MultiProvider([ + ['name' => 'Primary', 'provider' => new UnstableProvider()], + ['name' => 'Secondary', 'provider' => new StableProvider()], + ['name' => 'Tertiary', 'provider' => new LocalProvider()], +], new FirstSuccessfulStrategy()); +``` + +**Behavior:** +- Evaluates providers in order until one succeeds +- Ignores **all types of errors** from failing providers +- Returns the first successful result +- If all providers fail → returns default value with aggregated errors + +##### ComparisonStrategy + +Evaluates **all providers** at one time. If every provider returns a successful result with the same value, then that result is returned. Otherwise, an error is returned immediately if any provider errors. When values do not agree, the configured "fallback provider" value will be used. + +This strategy accepts several arguments during initialization: + +```php +use OpenFeature\implementation\multiprovider\strategy\ComparisonStrategy; + +// Set up providers +$providerA = new ProviderA(); +$multiProvider = new MultiProvider([ + ['provider' => $providerA], + ['provider' => new ProviderB()], +], new ComparisonStrategy( + $providerA, // First argument: "fallback provider" whose value to use when providers don't agree + function($resolutions) { // Second argument: callback when values don't match + error_log('Mismatch detected: ' . json_encode($resolutions)); + } +)); +``` + +The first argument is the "fallback provider" whose value to use in the event that providers do not agree. It should be the same object reference as one of the providers in the list. The second argument is a callback function that will be executed when a mismatch is detected. The callback will be passed an array containing the details of each provider's resolution, including the flag key, the value returned, and any errors that were thrown. + +**Use cases:** +- A/B testing during provider migrations +- Validating new provider implementations against trusted baselines +- Detecting configuration drift across multiple sources +- Ensuring provider consistency before committing to a new provider + +**Behavior:** +- Evaluates **ALL providers** sequentially +- **Fail-fast on errors:** If ANY provider returns an error, immediately returns all errors (no partial results) +- **Compares values:** Uses strict equality (`===`) to check if all providers returned the same value +- **On agreement:** If all providers succeed and all values match, returns the common value +- **On mismatch:** If all succeed but values don't match, calls optional `onMismatch` callback, then returns the fallback provider's value +- **Throws exception** if fallback provider not found in results + +**Important Notes:** +- The fallback provider parameter is **required** (not optional) +- Fallback provider must be included in the provider list +- This is **not** a "highest value wins" strategy - it checks for exact equality +- Fallback provider is only used for value mismatches, NOT for error recovery +- Useful for ensuring consistency during migrations, not for aggregating different values + +**Strategy Comparison** + +| Scenario | FirstMatchStrategy | FirstSuccessfulStrategy | ComparisonStrategy | +|----------|-------------------|------------------------|-------------------| +| Provider order matters | ✅ Yes (stops at first match) | ✅ Yes (stops at first success) | ❌ No (evaluates all) | +| Handles FLAG_NOT_FOUND | Continues to next | Continues to next | Returns all errors | +| Handles other errors | Stops evaluation | Continues to next | Returns all errors immediately | +| Evaluates all providers | ❌ No | ❌ No | ✅ Yes | +| Best for fallback | ✅ | ✅ | ❌ | +| Best for high availability | ❌ | ✅ | ❌ | +| Best for consistency validation | ❌ | ❌ | ✅ | +| Requires fallback provider | ❌ Optional | ❌ Optional | ✅ Required | + +**Error Handling** + +Error handling varies by strategy: + +**FirstMatchStrategy:** +- Continues evaluation when providers throw `FLAG_NOT_FOUND` +- Stops and returns error if provider throws other errors +- Aggregates `FLAG_NOT_FOUND` errors if all providers fail + +**FirstSuccessfulStrategy:** +- Continues evaluation when providers throw any error +- Returns first successful result, ignoring all previous errors +- Aggregates all errors if all providers fail + +**ComparisonStrategy:** +- **Fail-fast:** Returns all errors immediately if ANY provider errors +- Fallback provider only used for value mismatches (not error recovery) +- All providers are evaluated (no short-circuiting on mismatches) +- On value mismatch: Invokes `onMismatch` callback, then returns fallback provider's value (not an error) + +**Error Aggregation:** + +When all providers fail, MultiProvider aggregates individual provider errors into a single detailed error message: + +```php +// Example: FirstMatchStrategy with all FLAG_NOT_FOUND +$result = $client->getBooleanDetails('non-existent-flag', false); +// Returns: value=false, reason=ERROR, +// error="Multi-provider evaluation failed with 3 provider error(s): [ProviderA]: Flag not found; [ProviderB]: Flag not found; [ProviderC]: Flag not found" + +// Example: ComparisonStrategy with provider errors +$result = $client->getBooleanDetails('some-flag', false); +// Returns: value=false, reason=ERROR, +// error="Multi-provider evaluation failed with 2 provider error(s): [ProviderA]: Connection timeout; [ProviderB]: Invalid configuration" +``` + +This detailed error aggregation helps with debugging by showing exactly which provider failed and why, similar to JavaScript's `AggregateError`. + +**Complete Example** + +```php +use OpenFeature\OpenFeatureAPI; +use OpenFeature\implementation\multiprovider\MultiProvider; +use OpenFeature\implementation\multiprovider\strategy\FirstMatchStrategy; + +// Set up providers +$remoteProvider = new LaunchDarklyProvider($config); +$cacheProvider = new RedisCacheProvider($redis); +$defaultProvider = new InMemoryProvider([ + 'feature-enabled' => true, + 'api-timeout' => 30, +]); + +// Configure MultiProvider with priority order +$multiProvider = new MultiProvider([ + ['name' => 'LaunchDarkly', 'provider' => $remoteProvider], + ['name' => 'Redis', 'provider' => $cacheProvider], + ['name' => 'Defaults', 'provider' => $defaultProvider], +], new FirstMatchStrategy()); + +// Register with OpenFeature +$api = OpenFeatureAPI::getInstance(); +$api->setProvider($multiProvider); + +// Use as normal +$client = $api->getClient(); +$enabled = $client->getBooleanValue('feature-enabled', false); + +// Evaluation flow: +// 1. Try LaunchDarkly → if FLAG_NOT_FOUND, continue +// 2. Try Redis → if FLAG_NOT_FOUND, continue +// 3. Try Defaults → returns value +// 4. If all fail → returns default with aggregated errors +``` + +**Custom Strategies** + +It is also possible to implement your own strategy if the above options do not fit your use case. To do so, create a class which extends `BaseEvaluationStrategy`: + +```php +use OpenFeature\implementation\multiprovider\strategy\BaseEvaluationStrategy; +use OpenFeature\implementation\multiprovider\strategy\ProviderContext; +use OpenFeature\implementation\multiprovider\strategy\StrategyContext; +use OpenFeature\implementation\multiprovider\ProviderResolutionResult; +use OpenFeature\implementation\multiprovider\FinalResult; +use OpenFeature\interfaces\provider\RunMode; + +class CustomStrategy extends BaseEvaluationStrategy +{ + // Set to RunMode::EVALUATE_ALL to evaluate all providers at one time + // or leave as default for sequential evaluation + public string $runMode = RunMode::SEQUENTIAL; + + /** + * Called before each provider is evaluated. + * Return false to skip evaluating this provider. + */ + public function shouldEvaluateThisProvider(ProviderContext $context): bool + { + // Custom logic to determine if this provider should be evaluated + return true; + } + + /** + * Called after a provider is evaluated (sequential mode only). + * Return false to stop evaluating remaining providers. + */ + public function shouldEvaluateNextProvider( + ProviderContext $context, + ProviderResolutionResult $result + ): bool { + // Custom logic to determine if evaluation should continue + return true; + } + + /** + * Called after all providers have been evaluated. + * Determines the final result to return based on all provider results. + */ + public function determineFinalResult( + StrategyContext $context, + array $resolutions + ): FinalResult { + // Custom logic to determine which result to return + // Can analyze all results and choose one, aggregate them, etc. + + // Example: Return first successful result + foreach ($resolutions as $resolution) { + if (!$resolution->hasError()) { + return new FinalResult( + $resolution->getDetails(), + $resolution->getProviderName(), + null + ); + } + } + + // All failed - return errors + return new FinalResult(null, null, $this->aggregateErrors($resolutions)); + } +} +``` + +The `$runMode` property determines whether the list of providers will be evaluated sequentially or at once (using `RunMode::EVALUATE_ALL`). + +The `shouldEvaluateThisProvider()` method is called just before a provider is evaluated by the Multi-Provider. If the function returns false, then the provider will be skipped instead of being evaluated. + +The `shouldEvaluateNextProvider()` method is called after a provider is evaluated in sequential mode. If it returns true, the next provider in the sequence will be called, otherwise no more providers will be evaluated. This method is not called when `$runMode` is `RunMode::EVALUATE_ALL`. + +The `determineFinalResult()` method is called after all providers have been evaluated, or the `shouldEvaluateNextProvider()` method returned false. It is called with an array of results from all the individual providers' evaluations. It returns the final result, or can throw an error if needed. + +#### Known Limitations + +**Sub-Provider Hooks Not Executed:** + +Currently, when using MultiProvider, hooks registered on individual sub-providers via `provider->getHooks()` are **not executed** during flag evaluation. Only hooks registered at the API, Client, and Invocation levels (plus MultiProvider's own hooks) are executed. + +In the JS-SDK reference implementation, each sub-provider's hooks are executed around each provider call via a dedicated `HookExecutor`. The PHP `Provider` interface extends `HooksGetter` (per OpenFeature Requirement 2.10), so the mechanism exists—it just isn't wired up in the current implementation. + +**Workaround:** Register hooks at the API or Client level instead of on individual providers: + +```php +// Instead of this (won't execute): +$providerA->addHooks($myHook); + +// Do this (will execute): +$client = $api->getClient(); +$client->addHooks($myHook); +``` + +This limitation will be addressed in a future release where per-provider hook execution will be implemented to match the JS-SDK behavior. + ### Targeting Sometimes, the value of a flag must consider some dynamic criteria about the application or user, such as the user's location, IP, email address, or the server's location. diff --git a/docs/reference/sdks/server/python.mdx b/docs/reference/sdks/server/python.mdx index a3d4b0078..3ae18d51f 100644 --- a/docs/reference/sdks/server/python.mdx +++ b/docs/reference/sdks/server/python.mdx @@ -9,7 +9,7 @@ This content has been automatically generated from python-sdk. Edits should be made here: https://github.com/open-feature/python-sdk Once a repo has been updated, docs can be generated by running: yarn update:sdk-docs -Last updated at Mon Jun 08 2026 09:46:34 GMT+0000 (Coordinated Universal Time) +Last updated at Wed Jul 01 2026 09:19:00 GMT+0000 (Coordinated Universal Time) --> import MCPInstall from '@site/src/partials/mcp-install'; diff --git a/docs/reference/sdks/server/ruby.mdx b/docs/reference/sdks/server/ruby.mdx index d089b991f..b1cbbfbed 100644 --- a/docs/reference/sdks/server/ruby.mdx +++ b/docs/reference/sdks/server/ruby.mdx @@ -10,7 +10,7 @@ This content has been automatically generated from ruby-sdk. Edits should be made here: https://github.com/open-feature/ruby-sdk Once a repo has been updated, docs can be generated by running: yarn update:sdk-docs -Last updated at Mon Jun 08 2026 09:46:35 GMT+0000 (Coordinated Universal Time) +Last updated at Wed Jul 01 2026 09:19:01 GMT+0000 (Coordinated Universal Time) --> import MCPInstall from '@site/src/partials/mcp-install'; diff --git a/docs/reference/sdks/server/rust.mdx b/docs/reference/sdks/server/rust.mdx index f8ea2130c..7064b6ec6 100644 --- a/docs/reference/sdks/server/rust.mdx +++ b/docs/reference/sdks/server/rust.mdx @@ -9,7 +9,7 @@ This content has been automatically generated from rust-sdk. Edits should be made here: https://github.com/open-feature/rust-sdk Once a repo has been updated, docs can be generated by running: yarn update:sdk-docs -Last updated at Mon Jun 08 2026 09:46:36 GMT+0000 (Coordinated Universal Time) +Last updated at Wed Jul 01 2026 09:19:02 GMT+0000 (Coordinated Universal Time) -->

diff --git a/src/datasets/sdks/sdk-compatibility.json b/src/datasets/sdks/sdk-compatibility.json index 13926faeb..e5801a255 100644 --- a/src/datasets/sdks/sdk-compatibility.json +++ b/src/datasets/sdks/sdk-compatibility.json @@ -4,8 +4,8 @@ "path": "/docs/reference/sdks/server/java", "category": "Server", "release": { - "href": "https://github.com/open-feature/java-sdk/releases/tag/v1.20.2", - "version": "1.20.2", + "href": "https://github.com/open-feature/java-sdk/releases/tag/v1.21.0", + "version": "1.21.0", "stable": true }, "spec": { @@ -64,8 +64,8 @@ "path": "/docs/reference/sdks/server/javascript", "category": "Server", "release": { - "href": "https://github.com/open-feature/js-sdk/releases/tag/server-sdk-v1.21.0", - "version": "1.21.0", + "href": "https://github.com/open-feature/js-sdk/releases/tag/server-sdk-v1.22.0", + "version": "1.22.0", "stable": true }, "spec": { @@ -124,8 +124,8 @@ "path": "/docs/reference/sdks/server/dotnet", "category": "Server", "release": { - "href": "https://github.com/open-feature/dotnet-sdk/releases/tag/v2.13.0", - "version": "2.13.0", + "href": "https://github.com/open-feature/dotnet-sdk/releases/tag/v2.14.0", + "version": "2.14.0", "stable": true }, "spec": { @@ -304,8 +304,8 @@ "path": "/docs/reference/sdks/server/php", "category": "Server", "release": { - "href": "https://github.com/open-feature/php-sdk/releases/tag/2.1.2", - "version": "2.1.2", + "href": "https://github.com/open-feature/php-sdk/releases/tag/2.2.0", + "version": "2.2.0", "stable": true }, "spec": { @@ -364,8 +364,8 @@ "path": "/docs/reference/sdks/client/web", "category": "Client", "release": { - "href": "https://github.com/open-feature/js-sdk/releases/tag/web-sdk-v1.8.0", - "version": "1.8.0", + "href": "https://github.com/open-feature/js-sdk/releases/tag/web-sdk-v1.9.0", + "version": "1.9.0", "stable": true }, "spec": {