Openfeature Flagd Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require aubes/openfeature-flagd-bundle symfony/http-client nyholm/psr7
   

2. Register the bundle in config/bundles.php:

   Aubes\OpenFeatureFlagdBundle\OpenFeatureFlagdBundle::class => ['all' => true],
   

3. Configure Flagd connection in config/packages/open_feature_flagd.yaml:

   open_feature_flagd:
       host: '%env(FLAGD_HOST)%'  # e.g., 'localhost' or 'flagd-service'
       port: 8013
   

4. Verify Flagd is running (e.g., via Docker or local instance).

First Use Case: Evaluating a Feature Flag

Inject the FlagdProvider and use OpenFeature’s API:

use OpenFeature\OpenFeatureAPI;
use OpenFeature\Providers\Flagd\FlagdProvider;

class FeatureService {
    public function __construct(private FlagdProvider $provider) {}

    public function checkDarkMode(): bool {
        return OpenFeatureAPI::getInstance()
            ->setProvider($this->provider)
            ->getClient()
            ->getBooleanValue('dark_mode', false);
    }
}

Implementation Patterns

Core Workflow: Feature Flag Evaluation

1. Initialize OpenFeature once (e.g., in a service constructor):

   OpenFeatureAPI::getInstance()->setProvider($flagdProvider);
   

2. Reuse the client for subsequent evaluations (thread-safe):

   $client = OpenFeatureAPI::getInstance()->getClient();
   $isEnabled = $client->getBooleanValue('feature_x', false);
   

3. Contextual Evaluation (pass user/environment context):

   $context = new Context(['userId' => '123']);
   $client->getBooleanValue('premium_feature', false, $context);
   

Integration with Symfony Services

• Dependency Injection: Autowire FlagdProvider directly or via OpenFeatureAPI.
• Scoped HTTP Client: Configure a dedicated client for Flagd (e.g., with retries/timeouts):

  # config/packages/framework.yaml
  framework:
      http_client:
          scoped_clients:
              flagd.client:
                  base_uri: 'http://flagd:8013'
                  timeout: 3
  

  # config/packages/open_feature_flagd.yaml
  open_feature_flagd:
      http_client: flagd.client
  

Advanced: Dynamic Provider Switching

Use the bundle alongside aubes/openfeature-bundle for framework-level features (e.g., attributes, Twig helpers):

# config/packages/open_feature.yaml
open_feature:
    provider: OpenFeature\Providers\Flagd\FlagdProvider

Then annotate controllers:

#[FeatureGate('analytics_enabled')]
public function analyticsDashboard(): Response { ... }

Gotchas and Tips

Pitfalls

1. Flagd Server Dependency:

   • The bundle requires a running Flagd instance (no local fallback). Test locally with:

     docker run -p 8013:8013 openfeature/flagd
     

   • Debugging: Use FLAGD_HOST=localhost and check Flagd logs for connection errors.

2. Protocol Mismatch:

   • Defaults to HTTP; switch to gRPC for high-throughput environments:

     open_feature_flagd:
         protocol: grpc
     

   • Note: gRPC requires additional dependencies (e.g., grpc/grpc).

3. Context Serialization:

   • OpenFeature contexts must be JSON-serializable. Avoid circular references or non-serializable objects (e.g., Doctrine entities). Use DTOs:

     $context = new Context(['user' => (array)$userEntity]);
     

Debugging Tips

• Enable HTTP Logging: Configure the Symfony HTTP client to log requests:

  framework:
      http_client:
          scoped_clients:
              flagd.client:
                  base_uri: '%env(FLAGD_URL)%'
                  logger: true  # Logs requests/responses
  

• Flagd CLI: Use flagd eval to test flags manually:

  flagd eval --host localhost:8013 --flag dark_mode
  

• Symfony Profiler: Integrate with aubes/openfeature-bundle for flag evaluation metrics in the profiler.

Extension Points

1. Custom Providers:
   • Override the FlagdProvider service to add middleware (e.g., auth headers):

     services:
         OpenFeature\Providers\Flagd\FlagdProvider:
             arguments:
                 $client: '@custom.flagd.client'
     

2. Event Listeners:
   • Subscribe to OpenFeature events (e.g., ProviderDidChange) for analytics:

     OpenFeatureAPI::getInstance()->addListener(new MyFlagEventListener());
     

3. Testing:
   • Mock FlagdProvider in tests:

     $mockProvider = $this->createMock(FlagdProvider::class);
     $mockProvider->method('getBooleanValue')->willReturn(true);
     OpenFeatureAPI::getInstance()->setProvider($mockProvider);