Add FFE exposure emission

src/DDTrace/OpenFeature/DataDogProvider.php

@@ -8,6 +8,7 @@
 use DDTrace\FeatureFlags\EvaluationDetails;
 use DDTrace\FeatureFlags\EvaluationErrorCode;
 use DDTrace\FeatureFlags\EvaluationReason;
+use DDTrace\FeatureFlags\Internal\Exposure\ExposureHook;
 use DDTrace\FeatureFlags\Internal\NoopWarningEmitter;
 use DDTrace\FeatureFlags\Internal\TriggerErrorWarningEmitter;
 use DDTrace\FeatureFlags\Internal\WarningEmitter;
@@ -30,7 +31,11 @@ final class DataDogProvider extends AbstractProvider
 
     public function __construct()
     {
-        $this->client = FeatureFlagsClient::createWithDependencies(null, new NoopWarningEmitter());
+        $this->client = FeatureFlagsClient::createWithDependencies(
+            null,
+            new NoopWarningEmitter(),
+            ExposureHook::createDefault()
+        );
         $this->warningEmitter = new TriggerErrorWarningEmitter();
     }
 

src/api/FeatureFlags/Client.php

@@ -3,35 +3,43 @@
 namespace DDTrace\FeatureFlags;
 
 use DDTrace\FeatureFlags\Internal\Evaluator;
+use DDTrace\FeatureFlags\Internal\EvaluationCompleted;
+use DDTrace\FeatureFlags\Internal\EvaluationCompletedHook;
+use DDTrace\FeatureFlags\Internal\Exposure\ExposureHook;
 use DDTrace\FeatureFlags\Internal\NativeEvaluator;
+use DDTrace\FeatureFlags\Internal\NoopEvaluationCompletedHook;
 use DDTrace\FeatureFlags\Internal\TriggerErrorWarningEmitter;
 use DDTrace\FeatureFlags\Internal\WarningEmitter;
 
 final class Client
 {
     private $evaluator;
     private $warningEmitter;
+    private $evaluationCompletedHook;
     private $warnedAboutNonProductionRuntime = false;
 
     private function __construct(
         Evaluator $evaluator,
-        WarningEmitter $warningEmitter
+        WarningEmitter $warningEmitter,
+        EvaluationCompletedHook $evaluationCompletedHook
     ) {
         $this->evaluator = $evaluator;
         $this->warningEmitter = $warningEmitter;
+        $this->evaluationCompletedHook = $evaluationCompletedHook;
     }
 
     public static function create()
     {
-        return self::createWithDependencies();
+        return self::createWithDependencies(null, null, ExposureHook::createDefault());
     }
 
     /**
      * @internal Tests and Datadog-owned bridge adapters only.
      */
     public static function createWithDependencies(
         $evaluator = null,
-        $warningEmitter = null
+        $warningEmitter = null,
+        $evaluationCompletedHook = null
     ) {
         if ($evaluator !== null && !$evaluator instanceof Evaluator) {
             throw new \InvalidArgumentException('Expected an Evaluator instance');
@@ -41,9 +49,14 @@ public static function createWithDependencies(
             throw new \InvalidArgumentException('Expected a WarningEmitter instance');
         }
 
+        if ($evaluationCompletedHook !== null && !$evaluationCompletedHook instanceof EvaluationCompletedHook) {
+            throw new \InvalidArgumentException('Expected an EvaluationCompletedHook instance');
+        }
+
         return new self(
             $evaluator ?: NativeEvaluator::createOrUnavailable(),
-            $warningEmitter ?: new TriggerErrorWarningEmitter()
+            $warningEmitter ?: new TriggerErrorWarningEmitter(),
+            $evaluationCompletedHook ?: new NoopEvaluationCompletedHook()
         );
     }
 
@@ -111,10 +124,27 @@ private function evaluate($flagKey, $expectedType, $defaultValue, array $context
         );
 
         $this->warnIfNonProductionRuntime($details);
+        $this->evaluationCompleted(new EvaluationCompleted(
+            $flagKey,
+            $expectedType,
+            $defaultValue,
+            $targetingKey,
+            $attributes,
+            $details
+        ));
 
         return $details;
     }
 
+    private function evaluationCompleted(EvaluationCompleted $evaluation)
+    {
+        try {
+            $this->evaluationCompletedHook->evaluationCompleted($evaluation);
+        } catch (\Throwable $throwable) {
+            // Internal exposure/metric hooks must never affect flag evaluation results.
+        }
+    }
+
     private function normalizeContext(array $context)
     {
         $targetingKey = null;

src/api/FeatureFlags/Internal/EvaluationCompleted.php

@@ -0,0 +1,118 @@
+<?php
+
+namespace DDTrace\FeatureFlags\Internal;
+
+use DDTrace\FeatureFlags\EvaluationDetails;
+use DDTrace\FeatureFlags\EvaluationType;
+
+final class EvaluationCompleted
+{
+    private $flagKey;
+    private $valueType;
+    private $defaultValue;
+    private $targetingKey;
+    private $attributes;
+    private $details;
+
+    /**
+     * @param string $flagKey
+     * @param string $valueType One of EvaluationType::*.
+     * @param mixed $defaultValue
+     * @param string|null $targetingKey
+     * @param array<string, bool|int|float|string> $attributes
+     */
+    public function __construct(
+        $flagKey,
+        $valueType,
+        $defaultValue,
+        $targetingKey,
+        array $attributes,
+        EvaluationDetails $details
+    ) {
+        if (!is_string($flagKey) || $flagKey === '') {
+            throw new \InvalidArgumentException('Feature flag key must be a non-empty string');
+        }
+
+        if (!EvaluationType::isValid($valueType)) {
+            throw new \InvalidArgumentException('Unknown feature flag value type: ' . (string) $valueType);
+        }
+
+        if ($targetingKey !== null && !is_string($targetingKey)) {
+            throw new \InvalidArgumentException('Feature flag targeting key must be a string or null');
+        }
+
+        $this->flagKey = $flagKey;
+        $this->valueType = $valueType;
+        $this->defaultValue = $defaultValue;
+        $this->targetingKey = $targetingKey;
+        $this->attributes = $attributes;
+        $this->details = $details;
+    }
+
+    public function getFlagKey()
+    {
+        return $this->flagKey;
+    }
+
+    public function getValueType()
+    {
+        return $this->valueType;
+    }
+
+    public function getDefaultValue()
+    {
+        return $this->defaultValue;
+    }
+
+    public function getTargetingKey()
+    {
+        return $this->targetingKey;
+    }
+
+    public function getAttributes()
+    {
+        return $this->attributes;
+    }
+
+    public function getValue()
+    {
+        return $this->details->getValue();
+    }
+
+    public function getReason()
+    {
+        return $this->details->getReason();
+    }
+
+    public function getVariant()
+    {
+        return $this->details->getVariant();
+    }
+
+    public function getErrorCode()
+    {
+        return $this->details->getErrorCode();
+    }
+
+    public function getErrorMessage()
+    {
+        return $this->details->getErrorMessage();
+    }
+
+    public function getAllocationKey()
+    {
+        $exposureData = $this->details->getExposureData();
+        if (!isset($exposureData['allocationKey']) || !is_string($exposureData['allocationKey'])) {
+            return null;
+        }
+
+        return $exposureData['allocationKey'] === '' ? null : $exposureData['allocationKey'];
+    }
+
+    public function shouldLogExposure()
+    {
+        $exposureData = $this->details->getExposureData();
+
+        return isset($exposureData['doLog']) && $exposureData['doLog'] === true;
+    }
+}

src/api/FeatureFlags/Internal/EvaluationCompletedHook.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace DDTrace\FeatureFlags\Internal;
+
+interface EvaluationCompletedHook
+{
+    /**
+     * @return void
+     */
+    public function evaluationCompleted(EvaluationCompleted $evaluation);
+}