feat: Add support for client-side prerequisite events (#210)

Author: keelerm84

src/LaunchDarkly/FeatureFlagsState.php

@@ -43,7 +43,8 @@ public function addFlag(
         EvaluationDetail $detail,
         bool $forceReasonTracking = false,
         bool $withReason = false,
-        bool $detailsOnlyIfTracked = false
+        bool $detailsOnlyIfTracked = false,
+        ?array $prerequisites = null,
     ): void {
         $this->_flagValues[$flag->getKey()] = $detail->getValue();
         $meta = [];
@@ -60,6 +61,9 @@ public function addFlag(
 
         $reason = (!$withReason && !$trackReason) ? null : $detail->getReason();
 
+        if ($prerequisites) {
+            $meta['prerequisites'] = $prerequisites;
+        }
         if ($reason && !$omitDetails) {
             $meta['reason'] = $reason;
         }

src/LaunchDarkly/Impl/Evaluation/EvalResult.php

@@ -15,23 +15,35 @@
 class EvalResult
 {
     private EvaluationDetail $_detail;
+    private ?EvaluatorState $_state;
     private bool $_forceReasonTracking;
 
     /**
      * @param EvaluationDetail $detail
      * @param bool $forceReasonTracking
      */
-    public function __construct(EvaluationDetail $detail, bool $forceReasonTracking = false)
+    public function __construct(EvaluationDetail $detail, bool $forceReasonTracking = false, EvaluatorState $state = null)
     {
         $this->_detail = $detail;
+        $this->_state = $state;
         $this->_forceReasonTracking = $forceReasonTracking;
     }
 
+    public function withState(EvaluatorState $state): EvalResult
+    {
+        return new EvalResult($this->_detail, $this->_forceReasonTracking, $state);
+    }
+
     public function getDetail(): EvaluationDetail
     {
         return $this->_detail;
     }
 
+    public function getState(): ?EvaluatorState
+    {
+        return $this->_state;
+    }
+
     public function isForceReasonTracking(): bool
     {
         return $this->_forceReasonTracking;

src/LaunchDarkly/Impl/Evaluation/Evaluator.php

@@ -16,20 +16,6 @@
 use LaunchDarkly\Subsystems\FeatureRequester;
 use Psr\Log\LoggerInterface;
 
-/**
- * @ignore
- * @internal
- */
-class EvaluatorState
-{
-    public ?array $prerequisiteStack = null;
-    public ?array $segmentStack = null;
-    
-    public function __construct(public FeatureFlag $originalFlag)
-    {
-    }
-}
-
 /**
  * Encapsulates the feature flag evaluation logic. The Evaluator has no direct access to the
  * rest of the SDK environment; if it needs to retrieve flags or segments that are referenced
@@ -62,15 +48,15 @@ public function __construct(FeatureRequester $featureRequester, ?LoggerInterface
      */
     public function evaluate(FeatureFlag $flag, LDContext $context, ?callable $prereqEvalSink): EvalResult
     {
-        $stateStack = null;
         $state = new EvaluatorState($flag);
         try {
-            return $this->evaluateInternal($flag, $context, $prereqEvalSink, $state);
+            return $this->evaluateInternal($flag, $context, $prereqEvalSink, $state)
+                ->withState($state);
         } catch (EvaluationException $e) {
-            return new EvalResult(new EvaluationDetail(null, null, EvaluationReason::error($e->getErrorKind())));
+            return new EvalResult(new EvaluationDetail(null, null, EvaluationReason::error($e->getErrorKind())), false, $state);
         } catch (\Throwable $e) {
             Util::logExceptionAtErrorLevel($this->_logger, $e, 'Unexpected error when evaluating flag ' . $flag->getKey());
-            return new EvalResult(new EvaluationDetail(null, null, EvaluationReason::error(EvaluationReason::EXCEPTION_ERROR)));
+            return new EvalResult(new EvaluationDetail(null, null, EvaluationReason::error(EvaluationReason::EXCEPTION_ERROR)), false, $state);
         }
     }
 
@@ -144,14 +130,25 @@ private function checkPrerequisites(
                         EvaluationReason::MALFORMED_FLAG_ERROR
                     );
                 }
+
+                if ($state->depth == 0) {
+                    if ($state->prerequisites === null) {
+                        $state->prerequisites = [];
+                    }
+                    $state->prerequisites[] = $prereqKey;
+                }
+
+
                 $prereqOk = true;
                 $prereqFeatureFlag = $this->_featureRequester->getFeature($prereqKey);
                 if ($prereqFeatureFlag === null) {
                     $prereqOk = false;
                 } else {
                     // Note that if the prerequisite flag is off, we don't consider it a match no matter what its
                     // off variation was. But we still need to evaluate it in order to generate an event.
+                    $state->depth++;
                     $prereqEvalResult = $this->evaluateInternal($prereqFeatureFlag, $context, $prereqEvalSink, $state);
+                    $state->depth--;
                     $variation = $prereq->getVariation();
                     if (!$prereqFeatureFlag->isOn() || $prereqEvalResult->getDetail()->getVariationIndex() !== $variation) {
                         $prereqOk = false;

src/LaunchDarkly/Impl/Evaluation/EvaluatorState.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LaunchDarkly\Impl\Evaluation;
+
+use LaunchDarkly\Impl\Model\FeatureFlag;
+
+/**
+ * @ignore
+ * @internal
+ */
+class EvaluatorState
+{
+    public ?array $prerequisiteStack = null;
+    public ?array $segmentStack = null;
+    public ?array $prerequisites = null;
+    public int $depth = 0;
+
+    public function __construct(public FeatureFlag $originalFlag)
+    {
+    }
+}

src/LaunchDarkly/LDClient.php

@@ -501,7 +501,7 @@ public function allFlagsState(LDContext $context, array $options = []): FeatureF
                 continue;
             }
             $result = $tempEvaluator->evaluate($flag, $context, null);
-            $state->addFlag($flag, $result->getDetail(), $result->isForceReasonTracking(), $withReasons, $detailsOnlyIfTracked);
+            $state->addFlag($flag, $result->getDetail(), $result->isForceReasonTracking(), $withReasons, $detailsOnlyIfTracked, $result->getState()?->prerequisites);
         }
         return $state;
     }

test-service/TestService.php

@@ -77,7 +77,8 @@ public function getStatus(): array
                 'migrations',
                 'event-sampling',
                 'inline-context',
-                'anonymous-redaction'
+                'anonymous-redaction',
+                'client-prereq-events'
             ],
             'clientVersion' => \LaunchDarkly\LDClient::VERSION
         ];

tests/Impl/Evaluation/RolloutRandomizationConsistencyTest.php

@@ -63,7 +63,7 @@ public function buildFlag()
 
         return $decodedFlag;
     }
-    
+
     public function testVariationIndexForContext()
     {
         $flag = $this->buildFlag();
@@ -87,18 +87,21 @@ public function testVariationIndexForContext()
         );
 
         $evaluator = new Evaluator(static::$requester);
-    
+
         $context1 = LDContext::create('userKeyA');
         $result1 = $evaluator->evaluate($flag, $context1, EvaluatorTestUtil::expectNoPrerequisiteEvals());
-        $this->assertEquals($expectedEvalResult1, $result1);
+        $this->assertEquals($expectedEvalResult1->getDetail(), $result1->getDetail());
+        $this->assertEquals($expectedEvalResult1->isForceReasonTracking(), $result1->isForceReasonTracking());
 
         $context2 = LDContext::create('userKeyB');
         $result2 = $evaluator->evaluate($flag, $context2, EvaluatorTestUtil::expectNoPrerequisiteEvals());
-        $this->assertEquals($expectedEvalResult2, $result2);
+        $this->assertEquals($expectedEvalResult2->getDetail(), $result2->getDetail());
+        $this->assertEquals($expectedEvalResult2->isForceReasonTracking(), $result2->isForceReasonTracking());
 
         $context3 = LDContext::create('userKeyC');
         $result3 = $evaluator->evaluate($flag, $context3, EvaluatorTestUtil::expectNoPrerequisiteEvals());
-        $this->assertEquals($expectedEvalResult3, $result3);
+        $this->assertEquals($expectedEvalResult3->getDetail(), $result3->getDetail());
+        $this->assertEquals($expectedEvalResult3->isForceReasonTracking(), $result3->isForceReasonTracking());
     }
 
     public function testBucketContextByKey()