feat: Implement Multiprovider feature

[Tmakinde]

Summary

Adds a new feature that lets you plug in more than one feature flag provider at the same time. Instead of picking one provider up front, you can give the SDK a list, and it will try them in a defined order (or pattern) and return the first good answer. If none succeed, you get a single combined error.

Why this is useful

Real apps often use multiple sources for flags (primary remote service, fallback local file, experimentation provider, etc.). This feature avoids hand-written chaining logic and gives a simple, uniform way to try multiple providers.

How it works (plain flow)

1. You create a Multiprovider and pass an array of providers. You may optionally name each provider. If you do not name one, the code gives it a unique name automatically.
2. You call resolveXValue(...) (boolean, string, int, float, object) on the multiprovider.
3. A strategy decides which providers to try and when to stop.
4. Each provider is asked for the flag value (one at a time for the default strategy).
5. If one returns a successful value, that result is returned immediately.
6. If all fail (throw or error), a single error result is returned summarizing the failure.

Main classes in simple terms

• Multiprovider: The coordinator. Holds all the providers, calls them in order, chooses a strategy, and returns the final answer.
• BaseEvaluationStrategy: A template for “how to walk through the list.” It defines the decision points (should we try this provider? should we move to the next? how do we pick the final result?).
• FirstMatchStrategy (default): Tries providers in order, returns the first success, stops early.
• FirstSuccessfulStrategy: Alternative strategy with slightly different stop rules (still about first success).
• ProviderResolutionResult: A small wrapper for one provider’s attempt (either a value or an error).
• FinalResult: The final outcome after all attempts (either a single good value or a bundle of errors).
• StrategyEvaluationContext / StrategyPerProviderContext: Helper objects carrying flag info and provider-specific context so strategies can make simple yes/no decisions.

Backward compatibility

• Existing code using a single provider is unchanged.
• No existing public APIs were removed or altered.
• The new classes are additive and live in their own folder.
• If you do nothing, the SDK works exactly as before.

Testing

What was added:

• Tests for the multiprovider basic resolution path.
• Tests for strategies (ensuring the first matching provider wins; error path when all fail).
• Tests for final result object (success vs aggregated errors).
• Tests for validation (rejects duplicate explicit names, rejects empty name strings).

Simpler example

$multi = new Multiprovider([
    ['provider' => $primary],
    ['name' => 'audit', 'provider' => $audit],
    ['provider' => $fallback],
]);

$result = $multi->resolveBooleanValue('beta-feature', false);

$value = $result->getValue(); // either a resolved boolean or the default
$error = $result->getError(); // null if success

Follow-up improvements (non-blocking)

• README section explaining multi-provider setup.

[gemini-code-assist]

Summary of Changes

Hello @Tmakinde, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request establishes the foundational Multiprovider class, which is crucial for handling multiple feature flag providers. It focuses on robust input validation and systematic registration of providers, ensuring data integrity and preventing naming conflicts, thereby setting the stage for advanced multiprovider capabilities.

Highlights

• New Multiprovider Class: Introduced a new Multiprovider class to manage multiple feature flag providers, aligning with the OpenFeature multiprovider specification.
• Provider Data Validation: Implemented validateProviderData to ensure provider input arrays contain only supported keys, have non-empty names, and prevent duplicate explicit provider names.
• Provider Registration and Unique Naming: Developed registerProviders and uniqueProviderName methods to register providers by name, automatically generating unique names for providers that are unnamed or have conflicting names by appending a numerical suffix.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a Multiprovider class to handle multiple feature flag providers, which is a great step towards implementing the multi-provider feature from the OpenFeature specification. The implementation correctly handles validation of provider data structure and generation of unique names for unnamed providers. However, I've found a high-severity issue in the provider registration logic that could lead to providers being silently overwritten if there's a name collision between an explicitly named provider and a previously registered provider with a generated name. My review includes a suggested fix to prevent this and ensure all provider names are unique as required by the specification.

[tcarrio]

Hey @Tmakinde , initial thoughts here is that other languages utilized the contrib repository for implementing the multi provider. The reasoning as I understand it is it's an extension of the primary provider, not a function of it itself.

That said it would be fairly straightforward to add support for it there

@beeme1mr is that the expectation for all languages?

[Tmakinde]

Hey @Tmakinde , initial thoughts here is that other languages utilized the contrib repository for implementing the multi provider. The reasoning as I understand it is it's an extension of the primary provider, not a function of it itself.

That said it would be fairly straightforward to add support for it there

@beeme1mr is that the expectation for all languages?

Ooh.

Please let me know the best place to implement this.
@beeme1mr told me it should be in php-sdk repo.

Please confirm.

[beeme1mr]

We've been slowly moving the multi-providers to the SDKs themselves. The logic being that it's easier to access and manage provider state from within the SDK and it shouldn't add too much complexity to the SDKs. The .NET SDK is a good example of what we're looking for.

[Tmakinde]

We've been slowly moving the multi-providers to the SDKs themselves. The logic being that it's easier to access and manage provider state from within the SDK and it shouldn't add too much complexity to the SDKs. The .NET SDK is a good example of what we're looking for.

Thank you @beeme1mr

[codecov]

Codecov Report

❌ Patch coverage is 96.35036% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.57%. Comparing base (2123274) to head (86fffbf).
⚠️ Report is 31 commits behind head on main.

Files with missing lines	Patch %	Lines
...tion/multiprovider/strategy/ComparisonStrategy.php	91.30%	4 Missing ⚠️
src/implementation/multiprovider/MultiProvider.php	97.52%	3 Missing ⚠️
.../multiprovider/strategy/BaseEvaluationStrategy.php	84.61%	2 Missing ⚠️
...tion/multiprovider/strategy/FirstMatchStrategy.php	97.29%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main     #159      +/-   ##
============================================
+ Coverage     95.19%   96.57%   +1.37%     
- Complexity      227      335     +108     
============================================
  Files            40       49       +9     
  Lines           583      847     +264     
============================================
+ Hits            555      818     +263     
- Misses           28       29       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tcarrio]

I left some suggestions for the current PR state.

I am on vacation so can't provide a deeper review for some time.

[tcarrio]

@Tmakinde Beyond the suggestions in the PR thus far, would you be interested in being included as a code owner for the multiprovider namespace?

If so, feel free to update the code owners as part of this pull request.

[tcarrio]

No serious blockers, but some small updates you can make before we wrap. Now approving as the current implementation looks good to me.

[jonathannorris]

See the last two nits, but looks good! Thanks for implementing this!